@event4u/agent-config 1.18.0 → 1.19.0

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

@@ -26,11 +26,16 @@ from __future__ import annotations
 
 import argparse
 import datetime as _dt
-import json
 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"
@@ -79,9 +84,12 @@ def _read_onboarded(settings_path: Path) -> tuple[bool, str]:
 
 def _write_state(consumer_root: Path, required: bool, reason: str,
                  settings_present: bool) -> None:
-    """Write `agents/state/onboarding-gate.json` atomically."""
-    state_dir = consumer_root / STATE_DIR
-    state_dir.mkdir(parents=True, exist_ok=True)
+    """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,
@@ -89,10 +97,7 @@ def _write_state(consumer_root: Path, required: bool, reason: str,
             timespec="seconds"),
         "settings_present": settings_present,
     }
-    target = consumer_root / STATE_FILE
-    tmp = target.with_suffix(".json.tmp")
-    tmp.write_text(json.dumps(payload, indent=2) + "\n", encoding="utf-8")
-    tmp.replace(target)
+    atomic_write_json(consumer_root / STATE_FILE, payload)
 
 
 def run(*, consumer_root: Path, verbose: bool = False) -> int:

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/sync_agent_settings.py

@@ -1,15 +1,20 @@
 #!/usr/bin/env python3
-"""Sync `.agent-settings.yml` against the template + profile.
+"""Sync `.agent-settings.yml` against the template + profile (additive merge).
 
 Applies the section-aware merge rules documented in
 `docs/guidelines/agent-infra/layered-settings.md`:
 
-- Template section order always wins — reorder keys to match.
-- Existing user scalar values are preserved verbatim (as parsed).
-- Missing keys land with their template / profile default.
-- Template comments replace user comments in the same position.
-- Unknown user keys (not in the template) are preserved in a trailing
-  `_user:` block so custom additions never get silently dropped.
+- **User lines are preserved verbatim** — comments, quoting, and key order
+  survive every sync. Existing values, custom inline comments, and
+  user-chosen ordering are never modified.
+- Missing template keys are inserted (leaf into existing parent section,
+  full subtree at EOF for entirely missing top-level sections).
+- Top-level user-only sections (no home in the template) are moved to a
+  single-level `_user:` block at the end of the file.
+- The `_user:` block is single-level only — legacy multi-prefix
+  corruption (`_user._user.foo`) heals to `foo` on the next sync.
+- Template comment changes on already-existing user keys do **not**
+  propagate (existing line untouched is the deal).
 
 Idempotent — writing a file that is already in sync is a no-op.
 
@@ -33,7 +38,8 @@ import sys
 from pathlib import Path
 
 sys.path.insert(0, str(Path(__file__).resolve().parent))
-import install as _install  # noqa: E402 — shares _yaml_scalar + _replace_template_value
+import install as _install  # noqa: E402 — profile parsing + template rendering
+import sync_yaml_rt as _rt  # noqa: E402 — additive round-trip merge
 
 try:
     import yaml  # type: ignore
@@ -46,126 +52,6 @@ DEFAULT_TEMPLATE = Path(__file__).resolve().parent.parent / "config" / "agent-se
 DEFAULT_PROFILE_DIR = Path(__file__).resolve().parent.parent / "config" / "profiles"
 
 
-def _flatten(data: dict, prefix: str = "") -> dict[str, object]:
-    """Flatten nested dicts to dotted keys — recurses to all leaves.
-
-    Lists, scalars, and ``None`` are leaves. Dicts are walked and their
-    keys folded into the dotted path.
-    """
-    out: dict[str, object] = {}
-    for key, value in data.items():
-        path = f"{prefix}{key}"
-        if isinstance(value, dict):
-            out.update(_flatten(value, prefix=f"{path}."))
-        else:
-            out[path] = value
-    return out
-
-
-def _as_yaml_value(value: object) -> str | None:
-    """Format *value* as an inline-YAML literal.
-
-    Returns ``None`` when the value cannot be safely represented as a
-    scalar / flow-style sequence (e.g. unsupported types). Callers
-    must skip those keys so the template default sticks instead of
-    producing malformed YAML.
-    """
-    if isinstance(value, bool):
-        return "true" if value else "false"
-    if isinstance(value, int):
-        return str(value)
-    if isinstance(value, float):
-        return repr(value)
-    if value is None:
-        return "~"
-    if isinstance(value, list):
-        items: list[str] = []
-        for item in value:
-            rendered = _as_yaml_value(item)
-            if rendered is None:
-                return None
-            items.append(rendered)
-        return "[" + ", ".join(items) + "]"
-    if isinstance(value, str):
-        return _install._yaml_scalar(value)
-    return None
-
-
-def _template_keys(template_body: str) -> set[str]:
-    """Return the set of dotted keys declared by the rendered template."""
-    data = yaml.safe_load(template_body) or {}
-    if not isinstance(data, dict):
-        return set()
-    return set(_flatten(data).keys())
-
-
-def _apply_user_values(template_body: str, user_flat: dict[str, object]) -> str:
-    """Overlay every known user value on the rendered template body.
-
-    Keys whose value cannot be rendered inline (see :func:`_as_yaml_value`)
-    are skipped so the template default survives instead of corrupting
-    the file.
-    """
-    body = template_body
-    for dotted, value in user_flat.items():
-        rendered = _as_yaml_value(value)
-        if rendered is None:
-            continue
-        body = _install._replace_template_value_raw(body, dotted, rendered)
-    return body
-
-
-def _append_unknown(body: str, user_flat: dict[str, object], known: set[str]) -> str:
-    """Emit user keys that have no home in the template under `_user:`."""
-    unknown = sorted(k for k in user_flat if k not in known)
-    if not unknown:
-        return body
-    lines = [
-        "",
-        "# Unknown keys preserved by sync_agent_settings.py — review and move",
-        "# them into the template or drop them.",
-        "_user:",
-    ]
-    for key in unknown:
-        rendered = _as_yaml_value(user_flat[key])
-        if rendered is None:
-            continue
-        lines.append(f"  {key}: {rendered}")
-    suffix = "\n".join(lines) + "\n"
-    return body + (suffix if body.endswith("\n") else "\n" + suffix)
-
-
-def render_target(template_body: str, user_data: dict) -> str:
-    """Return the desired `.agent-settings.yml` body for the given user data.
-
-    The trailing ``_user:`` block (emitted by :func:`_append_unknown`) is
-    already in dotted-key form on every read after the first sync. Re-
-    flattening it would prepend another ``_user.`` segment on every run
-    and accumulate forever, so we strip the wrapper and merge its
-    contents straight into the flat dict.
-    """
-    if user_data:
-        user_only = user_data.pop("_user", None) if isinstance(user_data, dict) else None
-        user_flat = _flatten(user_data)
-        if isinstance(user_only, dict):
-            for key, value in user_only.items():
-                # Dotted keys round-trip verbatim — never re-flatten them.
-                if isinstance(key, str):
-                    # Heal legacy corruption: pre-fix syncs prepended a
-                    # `_user.` segment per run, so a key may carry an
-                    # arbitrary number of them. Strip them all back to
-                    # the original leaf path.
-                    healed = key
-                    while healed.startswith("_user."):
-                        healed = healed[len("_user."):]
-                    user_flat[healed] = value
-    else:
-        user_flat = {}
-    known = _template_keys(template_body)
-    body = _apply_user_values(template_body, user_flat)
-    return _append_unknown(body, user_flat, known)
-
-
 def load_profile(profile_dir: Path, profile: str) -> dict[str, str]:
     profile_source = profile_dir / f"{profile}.ini"
     if not profile_source.is_file():
@@ -231,10 +117,27 @@ def main(argv: list[str] | None = None) -> int:
     except FileNotFoundError as exc:
         print(f"error: {exc}", file=sys.stderr)
         return 2
+    except yaml.YAMLError as exc:
+        print(f"error: cannot parse {target}: {exc}", file=sys.stderr)
+        return 2
 
-    new_text = render_target(template_body, user_data)
     existing_text = target.read_text(encoding="utf-8") if target.is_file() else ""
 
+    if existing_text:
+        # Additive merge — preserves user lines verbatim, inserts only
+        # the template keys the user is missing.
+        try:
+            new_text = _rt.sync(existing_text, template_body)
+        except ValueError as exc:
+            print(
+                f"error: cannot parse {target}: {exc}",
+                file=sys.stderr,
+            )
+            return 2
+    else:
+        # First-run / file absent — write the rendered template as-is.
+        new_text = template_body
+
     if new_text == existing_text:
         if not args.quiet:
             print(f"✅  {target}: already in sync (profile={profile})")