@event4u/agent-config 1.18.0 → 1.19.0

package/scripts/install.sh

@@ -344,7 +344,7 @@ clean_stale() {
             log_verbose "preserve: $entry"
             continue
         fi
-        if is_excluded_rule "$entry" || ! echo "$source_manifest" | grep -qxF "$entry"; then
+        if is_excluded_rule "$entry" || ! grep -qxF -- "$entry" <<<"$source_manifest"; then
             local path="$target_dir/$entry"
             if $DRY_RUN; then
                 log_verbose "remove stale: $entry"

package/scripts/lint_hook_manifest.py

@@ -0,0 +1,216 @@
+#!/usr/bin/env python3
+"""Lint `scripts/hook_manifest.yaml`.
+
+CI gate per roadmap step 7.10. Hard-fails on:
+
+- missing or malformed top-level keys (`schema_version`, `concerns`,
+  `platforms`)
+- a concern entry referencing a non-existent script file
+- a platform binding referencing an unknown concern name
+- a platform binding referencing an unknown event (outside the
+  vocabulary in `docs/contracts/hook-architecture-v1.md`)
+- a `native_event_aliases` block referencing an unknown agent-config
+  event or an unknown platform
+- a `scripts/hooks/<platform>-dispatcher.sh` trampoline that exists on
+  disk without a corresponding non-empty platform block in the
+  manifest (orphan trampoline)
+
+Soft-warns on:
+
+- platform blocks set to `null` / empty (Phase 7.5–7.8 placeholders)
+- concerns declared but not bound to any platform (dead concern)
+
+Exit codes:
+  0 — clean (warnings allowed)
+  1 — at least one hard failure
+  2 — file or schema-load error
+
+Invocation:
+
+    python3 scripts/lint_hook_manifest.py [--manifest PATH] [--strict]
+
+`--strict` upgrades warnings to errors. Wired into `task ci` via the
+`lint-hook-manifest` task.
+"""
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+DEFAULT_MANIFEST = REPO_ROOT / "scripts" / "hook_manifest.yaml"
+HOOKS_DIR = REPO_ROOT / "scripts" / "hooks"
+
+# Canonical event vocabulary — keep in lock-step with
+# docs/contracts/hook-architecture-v1.md and dispatch_hook.EVENT_VOCABULARY.
+# `agent_error` added in Round 2 (2026-05-04) — synthetic event the
+# wrapper fires on host crashes outside a concern.
+EVENT_VOCABULARY: set[str] = {
+    "session_start", "session_end",
+    "user_prompt_submit",
+    "pre_tool_use", "post_tool_use",
+    "stop", "pre_compact",
+    "agent_error",
+}
+
+# Known platform identifiers. New platforms MUST be added here as they
+# land — the linter is the gate that proves no orphan slot escapes.
+KNOWN_PLATFORMS: set[str] = {
+    "augment", "claude", "cursor", "cline", "windsurf", "gemini", "copilot",
+}
+
+
+def _load_manifest(path: Path) -> dict:
+    """Reuse the dispatcher's loader so the linter sees exactly what
+    the runtime sees — including the fallback parser when PyYAML is
+    not installed."""
+    sys.path.insert(0, str(REPO_ROOT / "scripts"))
+    from hooks.dispatch_hook import _load_yaml  # noqa: E402
+    return _load_yaml(path)
+
+
+def _check_concerns(manifest: dict, errors: list[str]) -> set[str]:
+    concerns = manifest.get("concerns") or {}
+    if not isinstance(concerns, dict) or not concerns:
+        errors.append("manifest: 'concerns' must be a non-empty mapping")
+        return set()
+    names: set[str] = set()
+    for name, spec in concerns.items():
+        if not isinstance(spec, dict):
+            errors.append(f"concerns.{name}: must be a mapping, got {type(spec).__name__}")
+            continue
+        script = spec.get("script")
+        if not script or not isinstance(script, str):
+            errors.append(f"concerns.{name}: 'script' must be a relative path")
+            continue
+        if not (REPO_ROOT / script).is_file():
+            errors.append(f"concerns.{name}: script not found at '{script}'")
+        names.add(name)
+    return names
+
+
+def _check_platforms(manifest: dict, concern_names: set[str],
+                     errors: list[str], warnings: list[str]) -> set[str]:
+    platforms = manifest.get("platforms") or {}
+    if not isinstance(platforms, dict) or not platforms:
+        errors.append("manifest: 'platforms' must be a non-empty mapping")
+        return set()
+    bound: set[str] = set()
+    for plat, block in platforms.items():
+        if plat not in KNOWN_PLATFORMS:
+            errors.append(f"platforms.{plat}: unknown platform "
+                          f"(allowed: {sorted(KNOWN_PLATFORMS)})")
+            continue
+        if block is None:
+            warnings.append(f"platforms.{plat}: placeholder (no events bound)")
+            continue
+        if not isinstance(block, dict):
+            errors.append(f"platforms.{plat}: must be mapping or null")
+            continue
+        if block.get("fallback_only"):
+            continue  # Copilot — intentional, no event surface
+        for event, names in block.items():
+            if event not in EVENT_VOCABULARY:
+                errors.append(f"platforms.{plat}.{event}: unknown event "
+                              f"(allowed: {sorted(EVENT_VOCABULARY)})")
+                continue
+            if not isinstance(names, list):
+                errors.append(f"platforms.{plat}.{event}: must be a list of concern names")
+                continue
+            for n in names:
+                if n not in concern_names:
+                    errors.append(f"platforms.{plat}.{event}: unknown concern '{n}'")
+                else:
+                    bound.add(n)
+    return bound
+
+
+def _check_aliases(manifest: dict, errors: list[str]) -> None:
+    aliases = manifest.get("native_event_aliases") or {}
+    if not isinstance(aliases, dict):
+        errors.append("native_event_aliases: must be a mapping")
+        return
+    for plat, mapping in aliases.items():
+        if plat not in KNOWN_PLATFORMS:
+            errors.append(f"native_event_aliases.{plat}: unknown platform")
+            continue
+        if not isinstance(mapping, dict):
+            errors.append(f"native_event_aliases.{plat}: must be a mapping")
+            continue
+        for native, target in mapping.items():
+            if target not in EVENT_VOCABULARY:
+                errors.append(f"native_event_aliases.{plat}.{native}: "
+                              f"target '{target}' not in vocabulary")
+
+
+def _check_orphan_trampolines(manifest: dict, errors: list[str]) -> None:
+    """A `<platform>-dispatcher.sh` on disk MUST have a non-null,
+    non-empty manifest block — otherwise the trampoline runs but no
+    concerns fire (silent no-op, hardest class of bug to debug)."""
+    if not HOOKS_DIR.is_dir():
+        return
+    platforms = manifest.get("platforms") or {}
+    for entry in sorted(HOOKS_DIR.iterdir()):
+        if not entry.name.endswith("-dispatcher.sh"):
+            continue
+        plat = entry.name[: -len("-dispatcher.sh")]
+        if plat not in KNOWN_PLATFORMS:
+            errors.append(f"orphan trampoline {entry.name}: unknown platform '{plat}'")
+            continue
+        block = platforms.get(plat)
+        if block is None or (isinstance(block, dict)
+                             and not any(k in EVENT_VOCABULARY for k in block)):
+            errors.append(f"orphan trampoline {entry.name}: "
+                          f"platform '{plat}' has no event bindings in manifest")
+
+
+def _check_dead_concerns(concern_names: set[str], bound: set[str],
+                         warnings: list[str]) -> None:
+    for n in sorted(concern_names - bound):
+        warnings.append(f"concerns.{n}: declared but not bound to any platform")
+
+
+def lint(manifest_path: Path, *, strict: bool) -> int:
+    if not manifest_path.is_file():
+        sys.stderr.write(f"lint_hook_manifest: file not found: {manifest_path}\n")
+        return 2
+    try:
+        manifest = _load_manifest(manifest_path)
+    except Exception as exc:  # pragma: no cover — covered by malformed-yaml test
+        sys.stderr.write(f"lint_hook_manifest: load error: {exc}\n")
+        return 2
+    if not isinstance(manifest, dict) or manifest.get("schema_version") != 1:
+        sys.stderr.write("lint_hook_manifest: schema_version must be 1\n")
+        return 1
+
+    errors: list[str] = []
+    warnings: list[str] = []
+    concern_names = _check_concerns(manifest, errors)
+    bound = _check_platforms(manifest, concern_names, errors, warnings)
+    _check_aliases(manifest, errors)
+    _check_orphan_trampolines(manifest, errors)
+    _check_dead_concerns(concern_names, bound, warnings)
+
+    for w in warnings:
+        sys.stderr.write(f"warn: {w}\n")
+    for e in errors:
+        sys.stderr.write(f"error: {e}\n")
+
+    if errors:
+        return 1
+    if strict and warnings:
+        return 1
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--manifest", type=Path, default=DEFAULT_MANIFEST)
+    parser.add_argument("--strict", action="store_true")
+    args = parser.parse_args(argv)
+    return lint(args.manifest, strict=args.strict)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/scripts/lint_one_off_age.py

@@ -0,0 +1,184 @@
+#!/usr/bin/env python3
+"""One-off-script age linter.
+
+Scans `scripts/_one_off/<YYYY-MM>/_one_off_*.py` and enforces the
+TTL policy from `docs/contracts/one-off-script-lifecycle.md`:
+
+  * Age ≤ 60 days   → active, silent.
+  * 60 < Age ≤ 90   → warning, exit 0.
+  * Age > 90        → hard fail, exit 1 (purge candidate).
+
+Scripts MAY extend their TTL exactly once via a frontmatter block:
+
+    \"\"\"
+    ---
+    ttl_extended_until: YYYY-MM-DD
+    ttl_reason: <free text>
+    ---
+    \"\"\"
+
+The extended date is honoured up to 180 days past the month-directory
+date. Anything beyond hard-fails with no second extension.
+
+Exit codes: 0 = clean (incl. warnings), 1 = hard fail, 3 = internal error.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from dataclasses import asdict, dataclass
+from datetime import date, datetime, timezone
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent.parent
+ONE_OFF_DIR = ROOT / "scripts" / "_one_off"
+
+NAME_RE = re.compile(r"^_one_off_[a-z0-9-]+\.py$")
+MONTH_RE = re.compile(r"^\d{4}-\d{2}$")
+TTL_RE = re.compile(
+    r"---\s*\n\s*ttl_extended_until:\s*(\d{4}-\d{2}-\d{2})\s*\n",
+    re.MULTILINE,
+)
+
+WARN_DAYS = 60
+HARD_DAYS = 90
+EXTEND_CAP_DAYS = 180
+
+
+@dataclass
+class Finding:
+    path: str
+    age_days: int
+    severity: str  # "warn" | "fail"
+    reason: str
+
+
+def _today_utc() -> date:
+    return datetime.now(timezone.utc).date()
+
+
+def _month_anchor(month_dir: str) -> date | None:
+    if not MONTH_RE.match(month_dir):
+        return None
+    y, m = map(int, month_dir.split("-"))
+    try:
+        return date(y, m, 1)
+    except ValueError:
+        return None
+
+
+def _read_extension(path: Path) -> date | None:
+    try:
+        head = path.read_text(encoding="utf-8")[:1024]
+    except OSError:
+        return None
+    m = TTL_RE.search(head)
+    if not m:
+        return None
+    try:
+        return datetime.strptime(m.group(1), "%Y-%m-%d").date()
+    except ValueError:
+        return None
+
+
+def scan(root: Path, today: date | None = None) -> list[Finding]:
+    today = today or _today_utc()
+    base = root / "scripts" / "_one_off"
+    if not base.exists():
+        return []
+    out: list[Finding] = []
+    for month_dir in sorted(base.iterdir()):
+        if not month_dir.is_dir():
+            continue
+        anchor = _month_anchor(month_dir.name)
+        if anchor is None:
+            out.append(Finding(
+                path=str(month_dir.relative_to(root)),
+                age_days=-1,
+                severity="fail",
+                reason="invalid month directory name (expect YYYY-MM)",
+            ))
+            continue
+        for f in sorted(month_dir.iterdir()):
+            if f.name == "README.md" or f.is_dir():
+                continue
+            if not NAME_RE.match(f.name):
+                out.append(Finding(
+                    path=str(f.relative_to(root)),
+                    age_days=-1,
+                    severity="fail",
+                    reason="filename does not match _one_off_<slug>.py",
+                ))
+                continue
+            age = (today - anchor).days
+            extension = _read_extension(f)
+            if extension is not None:
+                cap = (extension - anchor).days
+                if cap > EXTEND_CAP_DAYS:
+                    out.append(Finding(
+                        path=str(f.relative_to(root)),
+                        age_days=age,
+                        severity="fail",
+                        reason=f"ttl_extended_until exceeds 180-day cap ({cap}d)",
+                    ))
+                    continue
+                if age <= cap:
+                    continue  # extension still valid, silent
+            if age > HARD_DAYS:
+                out.append(Finding(
+                    path=str(f.relative_to(root)),
+                    age_days=age,
+                    severity="fail",
+                    reason=f"age {age}d exceeds {HARD_DAYS}-day hard limit",
+                ))
+            elif age > WARN_DAYS:
+                out.append(Finding(
+                    path=str(f.relative_to(root)),
+                    age_days=age,
+                    severity="warn",
+                    reason=f"age {age}d in soft window ({WARN_DAYS}–{HARD_DAYS}d)",
+                ))
+    return out
+
+
+def format_text(findings: list[Finding]) -> str:
+    if not findings:
+        return "✅  No one-off-script age violations."
+    lines = []
+    fails = [f for f in findings if f.severity == "fail"]
+    warns = [f for f in findings if f.severity == "warn"]
+    if fails:
+        lines.append(f"❌  {len(fails)} one-off script(s) past hard limit:")
+        for f in fails:
+            lines.append(f"  🔴 {f.path}  →  {f.reason}")
+    if warns:
+        lines.append(f"⚠️  {len(warns)} one-off script(s) in soft window:")
+        for f in warns:
+            lines.append(f"  🟡 {f.path}  →  {f.reason}")
+    lines.append(
+        "\nPurge candidates per docs/contracts/one-off-script-lifecycle.md."
+    )
+    return "\n".join(lines)
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    parser.add_argument("--format", choices=["text", "json"], default="text")
+    parser.add_argument("--root", type=Path, default=ROOT)
+    args = parser.parse_args()
+    try:
+        findings = scan(args.root)
+    except Exception as e:    # pragma: no cover
+        print(f"Internal error: {e}", file=sys.stderr)
+        return 3
+    if args.format == "json":
+        print(json.dumps([asdict(f) for f in findings], indent=2))
+    else:
+        print(format_text(findings))
+    return 1 if any(f.severity == "fail" for f in findings) else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

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())