@event4u/agent-config 1.17.0 → 1.19.0

package/scripts/lint_rule_tiers.py

@@ -0,0 +1,78 @@
+#!/usr/bin/env python3
+"""Lint rule frontmatter for the `tier:` key.
+
+Hard-fails CI if any rule under .agent-src.uncompressed/rules/ lacks a
+`tier:` declaration or uses an unknown tier value. The valid tier set is
+locked by agents/contexts/hardening-pattern.md and the matrix in
+agents/contexts/rule-trigger-matrix.md.
+
+Hooked into `task ci` after `task lint-skills`.
+
+Exit codes:
+  0  every rule declares a valid tier
+  1  one or more rules missing or using an invalid tier
+"""
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+REPO = Path(__file__).resolve().parents[1]
+RULES_DIR = REPO / ".agent-src.uncompressed" / "rules"
+
+VALID_TIERS = frozenset({"1", "2a", "2b", "3", "safety-floor", "mechanical-already"})
+
+
+def parse_tier(text: str) -> str | None:
+    if not text.startswith("---\n"):
+        return None
+    end = text.find("\n---\n", 4)
+    if end == -1:
+        return None
+    for line in text[4:end].splitlines():
+        if ":" not in line:
+            continue
+        k, _, v = line.partition(":")
+        if k.strip() == "tier":
+            return v.strip().strip('"').strip("'")
+    return None
+
+
+def main() -> int:
+    rules = sorted(RULES_DIR.glob("*.md"))
+    if not rules:
+        print(f"lint_rule_tiers: no rules found under {RULES_DIR}", file=sys.stderr)
+        return 1
+
+    missing: list[str] = []
+    invalid: list[tuple[str, str]] = []
+
+    for rule in rules:
+        tier = parse_tier(rule.read_text(encoding="utf-8"))
+        if tier is None:
+            missing.append(rule.name)
+        elif tier not in VALID_TIERS:
+            invalid.append((rule.name, tier))
+
+    if missing or invalid:
+        print(
+            f"❌  lint_rule_tiers: {len(missing)} missing, "
+            f"{len(invalid)} invalid (of {len(rules)} rules)",
+            file=sys.stderr,
+        )
+        for name in missing:
+            print(f"    missing tier: {name}", file=sys.stderr)
+        for name, tier in invalid:
+            print(f"    invalid tier '{tier}': {name}", file=sys.stderr)
+        print(
+            f"    valid tiers: {sorted(VALID_TIERS)}",
+            file=sys.stderr,
+        )
+        return 1
+
+    print(f"✅  lint_rule_tiers: {len(rules)} rules, all tier values valid")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/scripts/lint_showcase_sessions.py

@@ -0,0 +1,148 @@
+#!/usr/bin/env python3
+"""lint_showcase_sessions.py — gate `docs/showcase.md` ↔ `docs/showcase/sessions/`.
+
+Phase 1.6 deliverable for `road-to-feedback-consolidation.md`.
+
+Rules:
+  1. Every `docs/showcase/sessions/<slug>.log` reference inside
+     `docs/showcase.md` must point to an existing file.
+  2. Every referenced session file must carry a YAML frontmatter block
+     containing at minimum `commit_sha` and a `metrics:` mapping (the
+     four outcome-baseline metrics; values may be null but the keys
+     must be present per `scripts/capture_showcase_session.py`).
+  3. Every file under `docs/showcase/sessions/` must be referenced
+     from `docs/showcase.md` — orphans are not allowed.
+
+When `docs/showcase/sessions/` is empty AND `docs/showcase.md` carries
+no session references, the linter exits 0 (clean — Phase 1.3-1.5 are
+deferred to manual host-agent runs).
+
+Exit codes:
+  0  clean
+  1  one or more violations
+"""
+from __future__ import annotations
+
+import re
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent.parent
+SHOWCASE_MD = ROOT / "docs" / "showcase.md"
+SESSIONS_DIR = ROOT / "docs" / "showcase" / "sessions"
+
+REQUIRED_METRICS = {
+    "tool_call_count",
+    "reply_chars_mean",
+    "memory_hit_ratio",
+    "verify_pass_rate",
+}
+
+REF_RE = re.compile(r"docs/showcase/sessions/([A-Za-z0-9_\-]+)\.log")
+
+
+def _parse_frontmatter(text: str) -> dict[str, str] | None:
+    if not text.startswith("---\n"):
+        return None
+    end = text.find("\n---\n", 4)
+    if end == -1:
+        return None
+    block: dict[str, str] = {}
+    current_key: str | None = None
+    nested: dict[str, str] = {}
+    for raw in text[4:end].splitlines():
+        if not raw.strip():
+            continue
+        if raw.startswith("  ") and current_key:
+            k, _, v = raw.strip().partition(":")
+            nested[k.strip()] = v.strip()
+            continue
+        if ":" not in raw:
+            continue
+        k, _, v = raw.partition(":")
+        v = v.strip()
+        if not v:
+            current_key = k.strip()
+            nested = {}
+            block[current_key] = ""
+            block[f"_{current_key}_nested"] = nested  # type: ignore[assignment]
+        else:
+            block[k.strip()] = v
+            current_key = None
+    return block
+
+
+def _validate_session(slug: str) -> list[str]:
+    errors: list[str] = []
+    path = SESSIONS_DIR / f"{slug}.log"
+    if not path.is_file():
+        errors.append(f"referenced session missing on disk: {path.relative_to(ROOT)}")
+        return errors
+    text = path.read_text(encoding="utf-8")
+    fm = _parse_frontmatter(text)
+    if fm is None:
+        errors.append(f"{slug}.log: no YAML frontmatter block")
+        return errors
+    if not fm.get("commit_sha"):
+        errors.append(f"{slug}.log: missing or empty `commit_sha`")
+    metrics = fm.get("_metrics_nested")
+    if not isinstance(metrics, dict):
+        errors.append(f"{slug}.log: missing `metrics:` mapping")
+    else:
+        missing = REQUIRED_METRICS - set(metrics.keys())
+        if missing:
+            errors.append(
+                f"{slug}.log: metrics block missing keys: {sorted(missing)}"
+            )
+    return errors
+
+
+def main() -> int:
+    if not SHOWCASE_MD.is_file():
+        print(f"❌  {SHOWCASE_MD.relative_to(ROOT)} not found", file=sys.stderr)
+        return 1
+
+    text = SHOWCASE_MD.read_text(encoding="utf-8")
+    referenced = set(REF_RE.findall(text))
+
+    on_disk: set[str] = set()
+    if SESSIONS_DIR.is_dir():
+        on_disk = {p.stem for p in SESSIONS_DIR.glob("*.log")}
+
+    errors: list[str] = []
+
+    for slug in sorted(referenced):
+        errors.extend(_validate_session(slug))
+
+    orphans = on_disk - referenced
+    for slug in sorted(orphans):
+        errors.append(
+            f"orphan session: docs/showcase/sessions/{slug}.log "
+            f"is not referenced from docs/showcase.md"
+        )
+
+    if errors:
+        print(
+            f"❌  lint_showcase_sessions: {len(errors)} violation(s) "
+            f"({len(referenced)} referenced, {len(on_disk)} on disk)",
+            file=sys.stderr,
+        )
+        for err in errors:
+            print(f"    {err}", file=sys.stderr)
+        return 1
+
+    if not referenced and not on_disk:
+        print(
+            "✅  lint_showcase_sessions: 0 sessions referenced, 0 on disk "
+            "(Phase 1.3-1.5 deferred to manual host-agent runs)"
+        )
+    else:
+        print(
+            f"✅  lint_showcase_sessions: {len(referenced)} session(s) "
+            f"valid ({len(on_disk)} on disk)"
+        )
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/scripts/minimal_safe_diff_hook.py

@@ -0,0 +1,245 @@
+#!/usr/bin/env python3
+"""Platform-agnostic hook for the `minimal-safe-diff` rule.
+
+Pre-edit gate: counts unique files touched in the current turn (or
+session, when the platform lacks a turn-boundary signal) and warns
+when the count exceeds the configured threshold. The hook never
+blocks — it is observability infra. The rule body cites the resulting
+state file when the agent prepares a diff for review.
+
+Wired to multiple events via the manifest:
+  - session_start / user_prompt_submit → reset turn-scoped counters
+  - pre_tool_use → record the planned edit's path before execution
+
+Output: `agents/state/minimal-safe-diff.json`
+  {
+    "schema_version": 1,
+    "session_id": "<str>",
+    "turn_started_at": "<iso8601|null>",
+    "files_touched_this_turn": ["a", "b", ...],
+    "count": <int>,
+    "threshold": <int>,
+    "warning": <bool>,
+    "checked_at": "<iso8601>"
+  }
+
+Exit code is always 0.
+"""
+from __future__ import annotations
+
+import argparse
+import datetime as _dt
+import json
+import re
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+from hooks.state_io import atomic_write_json  # noqa: E402
+
+STATE_FILE = Path("agents") / "state" / "minimal-safe-diff.json"
+SETTINGS_FILE = ".agent-settings.yml"
+DEFAULT_THRESHOLD = 5
+MAX_TRACKED_PATHS = 200  # hard cap to keep the state file bounded
+
+# Edit-tool names across platforms whose successful invocation results
+# in a file being modified, created, or deleted. Keep explicit so an
+# unknown tool doesn't trigger a false positive.
+EDIT_TOOLS = frozenset({
+    "str-replace-editor", "str_replace_editor",       # Augment
+    "save-file", "save_file",                          # Augment
+    "remove-files", "remove_files",                    # Augment
+    "Edit", "Write", "MultiEdit",                      # Claude Code
+    "edit_file", "edit-file",                          # Cursor
+    "create_file", "create-file", "delete_file",       # variants
+})
+
+
+def _now() -> str:
+    return _dt.datetime.now(_dt.timezone.utc).isoformat(timespec="seconds")
+
+
+def _empty_state(threshold: int) -> dict:
+    return {
+        "schema_version": 1,
+        "session_id": "",
+        "turn_started_at": None,
+        "files_touched_this_turn": [],
+        "count": 0,
+        "threshold": threshold,
+        "warning": False,
+        "checked_at": _now(),
+    }
+
+
+def _read_threshold(consumer_root: Path) -> int:
+    """Parse `hooks.minimal_safe_diff.threshold` from .agent-settings.yml.
+
+    Dependency-free YAML scan — we only need a single integer under a
+    nested block; pulling pyyaml in for this would be overkill.
+    """
+    settings = consumer_root / SETTINGS_FILE
+    if not settings.is_file():
+        return DEFAULT_THRESHOLD
+    try:
+        text = settings.read_text(encoding="utf-8")
+    except OSError:
+        return DEFAULT_THRESHOLD
+
+    in_hooks = False
+    in_msd = False
+    for raw in text.splitlines():
+        line = raw.rstrip()
+        if not line or line.lstrip().startswith("#"):
+            continue
+        # top-level key resets nested context
+        if line and not line.startswith((" ", "\t")):
+            in_hooks = re.match(r"^hooks\s*:\s*$", line) is not None
+            in_msd = False
+            continue
+        if in_hooks:
+            m = re.match(r"^\s+minimal_safe_diff\s*:\s*$", line)
+            if m:
+                in_msd = True
+                continue
+            # leaving the minimal_safe_diff block when indent decreases
+            if in_msd and re.match(r"^\s{0,3}\S", line):
+                in_msd = False
+        if in_msd:
+            m = re.match(r"^\s+threshold\s*:\s*(\d+)\s*(?:#.*)?$", line)
+            if m:
+                try:
+                    val = int(m.group(1))
+                    return val if val > 0 else DEFAULT_THRESHOLD
+                except ValueError:
+                    return DEFAULT_THRESHOLD
+    return DEFAULT_THRESHOLD
+
+
+def _load_state(target: Path, threshold: int) -> dict:
+    if not target.is_file():
+        return _empty_state(threshold)
+    try:
+        decoded = json.loads(target.read_text(encoding="utf-8"))
+        if isinstance(decoded, dict):
+            base = _empty_state(threshold)
+            base.update(decoded)
+            base["threshold"] = threshold  # always reflect current setting
+            return base
+    except (OSError, json.JSONDecodeError):
+        pass
+    return _empty_state(threshold)
+
+
+def _candidate_paths(payload: dict) -> list[str]:
+    out: list[str] = []
+    fc = payload.get("file_changes")
+    if isinstance(fc, list):
+        for entry in fc:
+            if isinstance(entry, dict):
+                p = entry.get("path")
+                if isinstance(p, str) and p:
+                    out.append(p)
+    ti = payload.get("tool_input")
+    if isinstance(ti, dict):
+        for key in ("path", "file_path", "target_file", "filename"):
+            v = ti.get(key)
+            if isinstance(v, str) and v:
+                out.append(v)
+    return out
+
+
+
+def _normalize(path: str) -> str:
+    return path.lstrip("./").replace("\\", "/")
+
+
+def _reset_turn(state: dict, session_id: str) -> dict:
+    state["session_id"] = session_id or state.get("session_id") or ""
+    state["turn_started_at"] = _now()
+    state["files_touched_this_turn"] = []
+    state["count"] = 0
+    state["warning"] = False
+    return state
+
+
+def _update(state: dict, event: str, envelope: dict, threshold: int) -> dict:
+    session_id = envelope.get("session_id") or state.get("session_id") or ""
+    if session_id and session_id != state.get("session_id"):
+        state = _reset_turn(state, session_id)
+
+    payload = envelope.get("payload") or {}
+    if not isinstance(payload, dict):
+        payload = {}
+
+    if event in ("session_start", "user_prompt_submit"):
+        state = _reset_turn(state, session_id)
+    elif event in ("pre_tool_use", "post_tool_use"):
+        tool = (payload.get("tool_name") or payload.get("toolName")
+                or payload.get("tool"))
+        if isinstance(tool, str) and tool in EDIT_TOOLS:
+            touched: list[str] = list(state.get("files_touched_this_turn") or [])
+            seen = set(touched)
+            for raw in _candidate_paths(payload):
+                norm = _normalize(raw)
+                if norm and norm not in seen:
+                    seen.add(norm)
+                    touched.append(norm)
+            if len(touched) > MAX_TRACKED_PATHS:
+                touched = touched[-MAX_TRACKED_PATHS:]
+            state["files_touched_this_turn"] = touched
+            state["count"] = len(touched)
+            state["warning"] = state["count"] > threshold
+
+    state["threshold"] = threshold
+    state["checked_at"] = _now()
+    return state
+
+
+def run(stdin_text: str, *, consumer_root: Path, verbose: bool = False) -> int:
+    envelope: dict = {}
+    if stdin_text.strip():
+        try:
+            decoded = json.loads(stdin_text)
+            if isinstance(decoded, dict):
+                envelope = decoded
+        except json.JSONDecodeError:
+            envelope = {}
+
+    event = envelope.get("event") or ""
+    threshold = _read_threshold(consumer_root)
+    target = consumer_root / STATE_FILE
+    state = _load_state(target, threshold)
+    state = _update(state, event, envelope, threshold)
+
+    try:
+        atomic_write_json(target, state)
+    except OSError:
+        if verbose:
+            print("minimal-safe-diff-hook: state write failed",
+                  file=sys.stderr)
+        return 0
+
+    if verbose:
+        print(
+            f"minimal-safe-diff-hook: event={event} "
+            f"count={state.get('count')} threshold={threshold} "
+            f"warning={state.get('warning')}",
+            file=sys.stderr,
+        )
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--platform", default="generic",
+                        help="informational platform tag")
+    parser.add_argument("--verbose", action="store_true",
+                        help="emit one stderr line per invocation")
+    args = parser.parse_args(argv)
+    return run(sys.stdin.read(), consumer_root=Path.cwd(),
+               verbose=args.verbose)
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())

package/scripts/onboarding_gate_hook.py

@@ -0,0 +1,142 @@
+#!/usr/bin/env python3
+"""Platform-agnostic hook for the `onboarding-gate` rule.
+
+Reads `.agent-settings.yml` from the consumer repo and writes a
+deterministic state file the rule body can cite as the source of
+truth for "do I need to prompt the user about /onboard?".
+
+Output is written to `agents/state/onboarding-gate.json` with:
+  {
+    "required": <bool>,         // true → rule fires on first turn
+    "reason":   "<string>",     // why this state was set
+    "checked_at": "<iso8601>",  // last hook run
+    "settings_present": <bool>  // .agent-settings.yml exists
+  }
+
+Exit code is **always 0**. Hooks must never block the agent loop.
+
+Output discipline:
+  - stdout: nothing (Augment surfaces stdout to the user)
+  - stderr: one short line in --verbose mode, otherwise silent
+
+CLI:
+  python3 scripts/onboarding_gate_hook.py [--platform NAME] [--verbose]
+"""
+from __future__ import annotations
+
+import argparse
+import datetime as _dt
+import re
+import sys
+from pathlib import Path
+
+# Re-use the shared atomic-write helper so concerns honour the single
+# `agents/state/.dispatcher.lock` discipline (hook-architecture-v1.md
+# § Concurrency, Phase 7.4).
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+from hooks.state_io import atomic_write_json  # noqa: E402
+
+SETTINGS_FILE = ".agent-settings.yml"
+STATE_DIR = Path("agents") / "state"
+STATE_FILE = STATE_DIR / "onboarding-gate.json"
+
+
+def _read_onboarded(settings_path: Path) -> tuple[bool, str]:
+    """Return (required, reason) — minimal, dependency-free YAML parsing.
+
+    We only need a single key under the `onboarding:` block. Full YAML is
+    overkill (and would pull in a runtime dep). We scan line-by-line for
+    `onboarded: <bool>` inside the `onboarding:` section.
+    """
+    if not settings_path.is_file():
+        return (False, "settings_file_missing")  # legacy: do not block
+
+    try:
+        text = settings_path.read_text(encoding="utf-8")
+    except OSError:
+        return (False, "settings_file_unreadable")
+
+    in_onboarding = False
+    onboarded_value: str | None = None
+    for raw in text.splitlines():
+        line = raw.rstrip()
+        if not line or line.lstrip().startswith("#"):
+            continue
+        if re.match(r"^onboarding\s*:\s*$", line):
+            in_onboarding = True
+            continue
+        if in_onboarding:
+            # Section ends when a top-level (non-indented) key starts.
+            if line and not line.startswith((" ", "\t")):
+                break
+            m = re.match(r"^\s+onboarded\s*:\s*(\S+)\s*(?:#.*)?$", line)
+            if m:
+                onboarded_value = m.group(1).strip().lower()
+
+    if onboarded_value is None:
+        return (False, "key_missing")  # legacy / pre-rule project
+    if onboarded_value in ("true", "yes", "on"):
+        return (False, "already_onboarded")
+    if onboarded_value in ("false", "no", "off"):
+        return (True, "explicit_false")
+    return (False, f"unknown_value:{onboarded_value}")
+
+
+def _write_state(consumer_root: Path, required: bool, reason: str,
+                 settings_present: bool) -> None:
+    """Write `agents/state/onboarding-gate.json` atomically.
+
+    Uses the shared `agents/state/.dispatcher.lock` so concurrent
+    dispatcher invocations across platforms cannot tear the file
+    (hook-architecture-v1.md § Concurrency, Phase 7.4).
+    """
+    payload = {
+        "required": required,
+        "reason": reason,
+        "checked_at": _dt.datetime.now(_dt.timezone.utc).isoformat(
+            timespec="seconds"),
+        "settings_present": settings_present,
+    }
+    atomic_write_json(consumer_root / STATE_FILE, payload)
+
+
+def run(*, consumer_root: Path, verbose: bool = False) -> int:
+    settings_path = consumer_root / SETTINGS_FILE
+    settings_present = settings_path.is_file()
+    try:
+        required, reason = _read_onboarded(settings_path)
+    except Exception:  # pragma: no cover — defensive
+        required, reason = (False, "hook_error")
+
+    try:
+        _write_state(consumer_root, required, reason, settings_present)
+    except OSError:
+        if verbose:
+            print("onboarding-gate-hook: state write failed",
+                  file=sys.stderr)
+        return 0  # never block
+
+    if verbose:
+        print(f"onboarding-gate-hook: required={required} reason={reason}",
+              file=sys.stderr)
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--platform", default="generic",
+                        help="informational platform tag")
+    parser.add_argument("--verbose", action="store_true",
+                        help="emit one stderr line per invocation")
+    args = parser.parse_args(argv)
+    # Drain stdin so callers piping JSON don't block on a SIGPIPE on
+    # platforms that strictly require stdin to be consumed.
+    try:
+        sys.stdin.read()
+    except Exception:
+        pass
+    return run(consumer_root=Path.cwd(), verbose=args.verbose)
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())

package/scripts/readme_linter.py

@@ -193,15 +193,24 @@ def _detect_repo_type(root: Path, ctx: RepoContext) -> RepoType:
 
 
 def _extract_taskfile_tasks(root: Path) -> list[str]:
+    tasks: list[str] = []
+    pattern = r"^\s{2}([\w:-]+):"
     for name in ("Taskfile.yml", "Taskfile.yaml"):
         path = root / name
         if path.exists():
             try:
-                text = path.read_text()
-                return re.findall(r"^\s{2}([\w_-]+):", text, re.MULTILINE)
+                tasks.extend(re.findall(pattern, path.read_text(), re.MULTILINE))
             except OSError:
                 pass
-    return []
+            break
+    taskfiles_dir = root / "taskfiles"
+    if taskfiles_dir.is_dir():
+        for path in sorted(taskfiles_dir.glob("*.yml")):
+            try:
+                tasks.extend(re.findall(pattern, path.read_text(), re.MULTILINE))
+            except OSError:
+                pass
+    return tasks
 
 
 def _extract_npm_scripts(root: Path) -> list[str]:

package/scripts/roadmap_progress_hook.py

@@ -114,6 +114,11 @@ def run(stdin_text: str, *, consumer_root: Path, verbose: bool = False) -> int:
         except json.JSONDecodeError:
             return 0  # malformed stdin → silent no-op, never block
 
+    # Unwrap dispatcher envelope (Phase 7.3, hook-architecture-v1.md).
+    if all(k in payload for k in ("schema_version", "platform", "event", "payload")):
+        inner = payload.get("payload")
+        payload = inner if isinstance(inner, dict) else {}
+
     tool = payload.get("tool_name") or payload.get("toolName") or payload.get("tool")
     if not isinstance(tool, str) or tool not in WRITE_TOOLS:
         return 0

package/scripts/schemas/rule.schema.json

@@ -33,6 +33,11 @@
       "type": "array",
       "items": {"type": "string", "pattern": "\\.md$"},
       "description": "Eager auto-loaded context references. Counts against the per-rule char budget; enforced by scripts/lint_load_context.py."
+    },
+    "tier": {
+      "type": "string",
+      "enum": ["1", "2a", "2b", "3", "safety-floor", "mechanical-already"],
+      "description": "Hardening tier per road-to-rule-hardening.md. Optional today, recommended for new rules. Tracked in agents/contexts/rule-trigger-matrix.md. Tier 3 rules also referenced in agents/contexts/tier-3-dispositions.md."
     }
   }
 }