@event4u/agent-config 1.17.0 → 1.18.0

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

package/scripts/onboarding_gate_hook.py

@@ -0,0 +1,137 @@
+#!/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 json
+import re
+import sys
+from pathlib import Path
+
+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."""
+    state_dir = consumer_root / STATE_DIR
+    state_dir.mkdir(parents=True, exist_ok=True)
+    payload = {
+        "required": required,
+        "reason": reason,
+        "checked_at": _dt.datetime.now(_dt.timezone.utc).isoformat(
+            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)
+
+
+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/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."
     }
   }
 }