@event4u/agent-config 1.17.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_examples.py

@@ -0,0 +1,98 @@
+#!/usr/bin/env python3
+"""Phase 3.4 demo-shape linter — wrong / right / why per demo.
+
+Cap: ≤ 100 LOC, stdlib only. Hooked into `task ci` via
+`Taskfile.yml` ▸ `check-examples-shape`. Validates every
+`docs/guidelines/agent-infra/*-demos.md`: frontmatter keys
+(`demo_for:`, `layer: pattern-memory`, `prose_delta:` with before /
+after char counts), and each `## Demo N` section having Wrong /
+Right shape headings, a `**Failure mode:**` line, and a Why-it-works
+explanation (heading or inline).
+"""
+from __future__ import annotations
+
+import re
+import sys
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+DEMO_GLOB = "docs/guidelines/agent-infra/*-demos.md"
+REQUIRED_FM_KEYS = ("demo_for:", "layer: pattern-memory", "prose_delta:")
+REQUIRED_FM_DELTA = ("rule_chars_before:", "rule_chars_after:")
+
+
+def _frontmatter(text: str) -> str:
+    if not text.startswith("---\n"):
+        return ""
+    end = text.find("\n---\n", 4)
+    return text[4:end] if end != -1 else ""
+
+
+def _check_frontmatter(fm: str, problems: list[str]) -> None:
+    for key in (*REQUIRED_FM_KEYS, *REQUIRED_FM_DELTA):
+        if key not in fm:
+            problems.append(f"frontmatter missing: {key!r}")
+
+
+def _check_demo_sections(text: str, problems: list[str]) -> None:
+    demo_pat = re.compile(r"^## Demo \d+\b.*$", re.MULTILINE)
+    demo_starts = [m.start() for m in demo_pat.finditer(text)]
+    if not demo_starts:
+        problems.append("no '## Demo N — …' sections found")
+        return
+    bounds = demo_starts + [len(text)]
+    for i, start in enumerate(demo_starts):
+        section = text[start:bounds[i + 1]]
+        title = section.splitlines()[0]
+        if "### Wrong shape" not in section:
+            problems.append(f"{title!r}: missing '### Wrong shape'")
+        if "### Right shape" not in section:
+            problems.append(f"{title!r}: missing '### Right shape'")
+        if "**Failure mode:**" not in section:
+            problems.append(f"{title!r}: missing '**Failure mode:**' line")
+        has_why_section = "### Why it works" in section
+        has_why_inline = "**Why it works:**" in section
+        if not (has_why_section or has_why_inline):
+            problems.append(
+                f"{title!r}: missing 'Why it works' explanation "
+                "(### Why it works or **Why it works:** inline)"
+            )
+
+
+def lint_demo(path: Path) -> list[str]:
+    text = path.read_text(encoding="utf-8")
+    problems: list[str] = []
+    fm = _frontmatter(text)
+    if not fm:
+        problems.append("missing YAML frontmatter (--- block at top)")
+    else:
+        _check_frontmatter(fm, problems)
+    _check_demo_sections(text, problems)
+    return problems
+
+
+def main() -> int:
+    demos = sorted(REPO_ROOT.glob(DEMO_GLOB))
+    if not demos:
+        print(f"❌  no demo files matched {DEMO_GLOB}", file=sys.stderr)
+        return 1
+    failed = 0
+    for demo in demos:
+        rel = demo.relative_to(REPO_ROOT)
+        problems = lint_demo(demo)
+        if problems:
+            failed += 1
+            print(f"❌  {rel}", file=sys.stderr)
+            for p in problems:
+                print(f"    - {p}", file=sys.stderr)
+        else:
+            print(f"✅  {rel}")
+    if failed:
+        print(f"\n❌  {failed} demo file(s) failed shape lint", file=sys.stderr)
+        return 1
+    print(f"\n✅  {len(demos)} demo file(s) shape-clean")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

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_roadmap_complexity.py

@@ -0,0 +1,127 @@
+#!/usr/bin/env python3
+"""Phase 5.2 roadmap-complexity linter.
+
+Enforces the measurable subset of
+`docs/contracts/roadmap-complexity-standard.md`:
+
+  - every `agents/roadmaps/*.md` declares `complexity: lightweight`
+    or `complexity: structural` in frontmatter;
+  - lightweight roadmaps have ≤ 600 total lines and ≤ 6 `## Phase N`
+    headings, and contain no `## Council Round N` / `### Verdict`
+    sections;
+  - structural roadmaps have no upper cap, but the tag must be
+    declared.
+
+Cap: ≤ 150 LOC, stdlib only. Hooked into `task ci` via
+`task lint-roadmap-complexity`.
+"""
+from __future__ import annotations
+
+import re
+import sys
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+ROADMAP_GLOB = "agents/roadmaps/*.md"
+LIGHTWEIGHT_LINE_CAP = 600
+LIGHTWEIGHT_PHASE_CAP = 6
+
+PHASE_PAT = re.compile(r"^## Phase \d+\b", re.MULTILINE)
+COUNCIL_PAT = re.compile(r"^## Council Round \d+\b", re.MULTILINE)
+VERDICT_PAT = re.compile(r"^### Verdict\b", re.MULTILINE)
+COMPLEXITY_PAT = re.compile(
+    r"^complexity:\s*(lightweight|structural)\s*$", re.MULTILINE
+)
+
+
+def _frontmatter(text: str) -> str:
+    if not text.startswith("---\n"):
+        return ""
+    end = text.find("\n---\n", 4)
+    return text[4:end] if end != -1 else ""
+
+
+def _read_complexity(fm: str) -> str | None:
+    m = COMPLEXITY_PAT.search(fm)
+    return m.group(1) if m else None
+
+
+def _check_lightweight(text: str, line_count: int, problems: list[str]) -> None:
+    if line_count > LIGHTWEIGHT_LINE_CAP:
+        problems.append(
+            f"lightweight cap exceeded: {line_count} lines "
+            f"(max {LIGHTWEIGHT_LINE_CAP}); consider tagging structural "
+            f"or trimming"
+        )
+    phases = len(PHASE_PAT.findall(text))
+    if phases > LIGHTWEIGHT_PHASE_CAP:
+        problems.append(
+            f"lightweight phase cap exceeded: {phases} phases "
+            f"(max {LIGHTWEIGHT_PHASE_CAP})"
+        )
+    if COUNCIL_PAT.search(text):
+        problems.append(
+            "lightweight roadmap contains '## Council Round N' "
+            "block — council debates belong in structural roadmaps"
+        )
+    if VERDICT_PAT.search(text):
+        problems.append(
+            "lightweight roadmap contains '### Verdict' block — "
+            "council verdicts belong in structural roadmaps"
+        )
+
+
+def lint_roadmap(path: Path) -> list[str]:
+    text = path.read_text(encoding="utf-8")
+    line_count = text.count("\n") + (1 if text and not text.endswith("\n") else 0)
+    problems: list[str] = []
+    fm = _frontmatter(text)
+    complexity = _read_complexity(fm) if fm else None
+    if complexity is None:
+        problems.append(
+            "missing 'complexity:' frontmatter "
+            "(must declare 'lightweight' or 'structural')"
+        )
+        return problems
+    if complexity == "lightweight":
+        _check_lightweight(text, line_count, problems)
+    return problems
+
+
+def main() -> int:
+    roadmaps = sorted(REPO_ROOT.glob(ROADMAP_GLOB))
+    if not roadmaps:
+        print(f"❌  no roadmaps matched {ROADMAP_GLOB}", file=sys.stderr)
+        return 1
+    failed = 0
+    summary: list[tuple[str, str]] = []
+    for roadmap in roadmaps:
+        rel = roadmap.relative_to(REPO_ROOT)
+        problems = lint_roadmap(roadmap)
+        text = roadmap.read_text(encoding="utf-8")
+        complexity = _read_complexity(_frontmatter(text)) or "untagged"
+        summary.append((str(rel), complexity))
+        if problems:
+            failed += 1
+            print(f"❌  {rel}  [{complexity}]", file=sys.stderr)
+            for p in problems:
+                print(f"    - {p}", file=sys.stderr)
+        else:
+            print(f"✅  {rel}  [{complexity}]")
+    print()
+    light = sum(1 for _, c in summary if c == "lightweight")
+    structural = sum(1 for _, c in summary if c == "structural")
+    untagged = sum(1 for _, c in summary if c == "untagged")
+    print(
+        f"summary: {light} lightweight · {structural} structural · "
+        f"{untagged} untagged · {len(summary)} total"
+    )
+    if failed:
+        print(f"\n❌  {failed} roadmap(s) failed complexity lint", file=sys.stderr)
+        return 1
+    print(f"\n✅  {len(roadmaps)} roadmap(s) complexity-clean")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())