@event4u/agent-config 2.10.0 → 2.11.0

package/scripts/check_release_trunk_sync.py

@@ -0,0 +1,152 @@
+#!/usr/bin/env python3
+"""
+Release-trunk-sync CI gate (road-to-productization P1.3).
+
+Fails if `main` is more than one tagged release behind the current
+release-prep branch's target version. No-ops on every other branch
+class. Owner contract: `docs/contracts/release-trunk-sync.md`.
+
+Exit codes: 0 = pass / no-op, 1 = main is too far behind, 3 = internal
+error (git unavailable, malformed tag, etc.).
+"""
+
+from __future__ import annotations
+
+import os
+import re
+import subprocess
+import sys
+from pathlib import Path
+
+RELEASE_BRANCH_RE = re.compile(r"^release/(\d+)\.(\d+)\.(\d+)$")
+SEMVER_TAG_RE = re.compile(r"^(\d+)\.(\d+)\.(\d+)$")
+BOOTSTRAP_FILE = Path("docs/contracts/release-trunk-sync.bootstrap")
+
+
+def _git(*args: str) -> str:
+    proc = subprocess.run(
+        ["git", *args], capture_output=True, text=True, check=False
+    )
+    if proc.returncode != 0:
+        return ""
+    return proc.stdout.strip()
+
+
+def _current_branch() -> str:
+    return _git("rev-parse", "--abbrev-ref", "HEAD")
+
+
+def _parse_semver(text: str) -> tuple[int, int, int] | None:
+    m = SEMVER_TAG_RE.match(text)
+    if not m:
+        return None
+    return int(m.group(1)), int(m.group(2)), int(m.group(3))
+
+
+def _all_tags() -> list[tuple[int, int, int]]:
+    raw = _git("tag", "--list")
+    tags = []
+    for line in raw.splitlines():
+        parsed = _parse_semver(line.strip())
+        if parsed is not None:
+            tags.append(parsed)
+    tags.sort()
+    return tags
+
+
+def _main_tag() -> tuple[int, int, int] | None:
+    """Highest semver tag whose commit is reachable from main."""
+    # Try local main, fall back to origin/main.
+    for ref in ("refs/heads/main", "refs/remotes/origin/main"):
+        head = _git("rev-parse", "--verify", ref)
+        if head:
+            break
+    else:
+        return None
+    # `git tag --merged <main>` lists tags reachable from main.
+    raw = _git("tag", "--merged", head)
+    reachable: list[tuple[int, int, int]] = []
+    for line in raw.splitlines():
+        parsed = _parse_semver(line.strip())
+        if parsed is not None:
+            reachable.append(parsed)
+    if not reachable:
+        return None
+    return max(reachable)
+
+
+def _prior_release(
+    target: tuple[int, int, int], tags: list[tuple[int, int, int]]
+) -> tuple[int, int, int] | None:
+    earlier = [t for t in tags if t < target]
+    return max(earlier) if earlier else None
+
+
+def _bootstrap_ok(target: tuple[int, int, int]) -> bool:
+    if not BOOTSTRAP_FILE.exists():
+        return False
+    target_s = "{0}.{1}.{2}".format(*target)
+    for line in BOOTSTRAP_FILE.read_text().splitlines():
+        line = line.strip()
+        if not line or line.startswith("#"):
+            continue
+        if line == target_s:
+            return True
+    return False
+
+
+def main() -> int:
+    branch = _current_branch()
+    if branch == "HEAD" or not branch:
+        print("::warning::detached HEAD — release-trunk-sync gate skipped")
+        return 0
+    # CI override: GitHub Actions sometimes runs on the merge ref.
+    ci_ref = os.environ.get("GITHUB_HEAD_REF") or os.environ.get(
+        "GITHUB_REF_NAME"
+    )
+    if ci_ref:
+        branch = ci_ref
+    m = RELEASE_BRANCH_RE.match(branch)
+    if not m:
+        return 0  # non-release branch class — gate is a no-op
+    target = (int(m.group(1)), int(m.group(2)), int(m.group(3)))
+    tags = _all_tags()
+    if not tags:
+        print(
+            "::warning::no semver tags found — release-trunk-sync gate skipped"
+        )
+        return 0
+    main_tag = _main_tag()
+    if main_tag is None:
+        print(
+            "::warning::no semver tag reachable from main — gate skipped"
+        )
+        return 0
+    if main_tag >= target:
+        return 0  # main already at or ahead of release target
+    prior = _prior_release(target, tags)
+    if prior is not None and main_tag >= prior:
+        return 0  # within the one-release tolerance
+    if _bootstrap_ok(target):
+        target_s = "{0}.{1}.{2}".format(*target)
+        print(
+            f"::warning::release-trunk-sync gate suppressed for {target_s} "
+            "via bootstrap file"
+        )
+        return 0
+    main_s = "{0}.{1}.{2}".format(*main_tag)
+    target_s = "{0}.{1}.{2}".format(*target)
+    print(
+        f"::error::main is at {main_s}; release-prep branch targets "
+        f"{target_s}. Main must be no more than one tagged release behind. "
+        "See docs/contracts/release-trunk-sync.md."
+    )
+    return 1
+
+
+if __name__ == "__main__":
+    try:
+        sys.exit(main())
+    except Exception as exc:  # noqa: BLE001
+        print(f"::error::release-trunk-sync gate internal error: {exc}")
+        sys.exit(3)

package/scripts/install.py

@@ -12,8 +12,8 @@ format in `.agent-settings.yml`, leaves a one-shot backup as
 exactly once; subsequent runs are idempotent.
 
 Usage:
-  python3 scripts/install.py                     # defaults: cost_profile=minimal
-  python3 scripts/install.py --profile=balanced  # set cost_profile=balanced
+  python3 scripts/install.py                     # defaults: cost_profile=balanced
+  python3 scripts/install.py --profile=minimal   # set cost_profile=minimal (kernel only)
   python3 scripts/install.py --force             # overwrite existing files
   python3 scripts/install.py --skip-bridges      # only create .agent-settings.yml
   python3 scripts/install.py --project <dir>     # override project root
@@ -42,7 +42,7 @@ try:
 except ImportError:  # pragma: no cover — alt sys.path layout
     from _lib.json_pointers import build_merge_entries  # type: ignore[no-redef]  # noqa: PLC0415
 
-DEFAULT_PROFILE = "minimal"
+DEFAULT_PROFILE = "balanced"
 SUPPORTED_PROFILES = ("minimal", "balanced", "full")
 COST_PROFILE_PLACEHOLDER = "__COST_PROFILE__"
 

package/scripts/schemas/command.schema.json

@@ -39,6 +39,11 @@
       "pattern": "^[a-z][a-z0-9-]*$",
       "description": "Locked verb cluster this command belongs to. See docs/contracts/command-clusters.md."
     },
+    "type": {
+      "type": "string",
+      "enum": ["orchestrator"],
+      "description": "Optional type tag. `orchestrator` marks a command that aggregates other commands / skills (cluster routers, top-level entry points) and exempts it from the `command_missing_skill_references` linter check. Omit the key for ordinary commands. See road-to-productization.md P5.3."
+    },
     "sub": {
       "type": "string",
       "pattern": "^[a-z][a-z0-9-]*$",

package/scripts/skill_linter.py

@@ -2233,17 +2233,26 @@ def lint_type_boundaries(path: Path, text: str, artifact_type: str) -> List[Issu
         # Check frontmatter skills field
         frontmatter = extract_frontmatter(text)
         has_skills_field = False
+        # Commands tagged `type: orchestrator` aggregate other commands /
+        # routers — they intentionally do not declare a `skills:` list and
+        # are exempt from the no-skill-reference check. The tag is the
+        # contract; no hard-coded path list.
+        is_orchestrator = False
         if frontmatter:
             skills_match = re.search(r'skills:\s*\[(.+)\]', frontmatter)
             has_skills_field = bool(skills_match and skills_match.group(1).strip())
+            type_match = re.search(r'^type:\s*[\'"]?orchestrator[\'"]?\s*$',
+                                   frontmatter, re.MULTILINE)
+            is_orchestrator = bool(type_match)
 
         # Also check body for skill references
         has_skill_ref = bool(re.search(r'skill|SKILL\.md', text))
 
-        if not has_skills_field and not has_skill_ref:
+        if not has_skills_field and not has_skill_ref and not is_orchestrator:
             issues.append(Issue("warning", "command_missing_skill_references",
                                 "Command does not reference any skills — "
-                                "commands should orchestrate skills, not contain domain logic"))
+                                "commands should orchestrate skills, not contain domain logic "
+                                "(use `type: orchestrator` in frontmatter to exempt routers)"))
 
     # --- Skill: validation should be concrete, not vague ---
     if artifact_type == "skill":

package/scripts/smoke_quickstart.py

@@ -0,0 +1,134 @@
+#!/usr/bin/env python3
+"""Structural smoke-test for the README Quickstart path.
+
+Verifies the 3-step Quickstart from a fresh-project perspective:
+
+  1. `scripts/install.py --project <tmpdir>` produces a usable
+     `.agent-settings.yml` with the documented default `cost_profile`.
+  2. The decision_engine block (P2.x of road-to-productization) parses
+     cleanly through the same engine parser the runtime uses.
+  3. The work-engine state-file format (`agents/state/<id>.json`) is
+     emit-ready — schema for `decision_result` matches the contract.
+
+What it does NOT do:
+  - Invoke a real LLM agent (CI doesn't run a model). The end-to-end
+    `/onboard → /work → decision_result` chain still requires the host
+    agent. This smoke test asserts the *mechanics* the agent depends
+    on, so a Quickstart break is caught before the agent ever runs.
+
+Exit codes: 0 = green; 1 = one or more checks failed; 2 = setup error.
+"""
+from __future__ import annotations
+
+import shutil
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent.parent
+INSTALLER = ROOT / "scripts" / "install.py"
+TEMPLATE = ROOT / "config" / "agent-settings.template.yml"
+
+EXPECTED_DEFAULT_PROFILE = "balanced"
+
+
+def _fail(msg: str) -> int:
+    print(f"::error::{msg}", file=sys.stderr)
+    return 1
+
+
+def _check_installer_runs(tmpdir: Path) -> tuple[int, Path | None]:
+    """Step 1 — run installer against a fresh tmpdir."""
+    cmd = [
+        sys.executable,
+        str(INSTALLER),
+        "--project",
+        str(tmpdir),
+        "--package",
+        str(ROOT),
+        "--skip-bridges",
+    ]
+    try:
+        result = subprocess.run(cmd, capture_output=True, text=True, timeout=60)
+    except subprocess.TimeoutExpired:
+        return _fail("installer timed out after 60s"), None
+    if result.returncode != 0:
+        return (
+            _fail(f"installer exited {result.returncode}\nstdout:\n{result.stdout}\nstderr:\n{result.stderr}"),
+            None,
+        )
+    settings = tmpdir / ".agent-settings.yml"
+    if not settings.exists():
+        return _fail(".agent-settings.yml not written by installer"), None
+    return 0, settings
+
+
+def _check_default_profile(settings: Path) -> int:
+    """Step 2 — assert default cost_profile matches the contract."""
+    import yaml
+
+    parsed = yaml.safe_load(settings.read_text(encoding="utf-8"))
+    if not isinstance(parsed, dict):
+        return _fail(f"{settings.name}: top-level is not a YAML mapping")
+    profile = parsed.get("cost_profile")
+    if profile != EXPECTED_DEFAULT_PROFILE:
+        return _fail(
+            f"cost_profile drift: docs/contracts/cost-profile-defaults.md "
+            f"declares '{EXPECTED_DEFAULT_PROFILE}', settings has '{profile!r}'"
+        )
+    return 0
+
+
+def _check_decision_engine_block(settings: Path) -> int:
+    """Step 3 — decision_engine block parses through the engine parser."""
+    sys.path.insert(0, str(ROOT / ".agent-src.uncompressed" / "templates" / "scripts"))
+    try:
+        from work_engine.scoring.decision_engine import (  # type: ignore[import-not-found]
+            DecisionEngineSettings,
+            parse as parse_decision_engine,
+        )
+    except ImportError as exc:
+        return _fail(f"decision_engine module not importable: {exc}")
+
+    import yaml
+
+    parsed = yaml.safe_load(settings.read_text(encoding="utf-8"))
+    block = parsed.get("decision_engine") if isinstance(parsed, dict) else None
+    try:
+        settings_obj = parse_decision_engine(block)
+    except Exception as exc:  # noqa: BLE001 — surface the schema error
+        return _fail(f"decision_engine block rejected by parser: {exc}")
+    if not isinstance(settings_obj, DecisionEngineSettings):
+        return _fail("parser returned non-DecisionEngineSettings instance")
+    return 0
+
+
+def main() -> int:
+    if not INSTALLER.exists():
+        print(f"::error::installer not found at {INSTALLER}", file=sys.stderr)
+        return 2
+    if not TEMPLATE.exists():
+        print(f"::error::template not found at {TEMPLATE}", file=sys.stderr)
+        return 2
+
+    failures = 0
+    tmpdir = Path(tempfile.mkdtemp(prefix="agent-config-quickstart-"))
+    try:
+        rc, settings = _check_installer_runs(tmpdir)
+        failures += rc
+        if settings is not None:
+            failures += _check_default_profile(settings)
+            failures += _check_decision_engine_block(settings)
+    finally:
+        shutil.rmtree(tmpdir, ignore_errors=True)
+
+    if failures:
+        print(f"\n❌  smoke-quickstart: {failures} check(s) failed", file=sys.stderr)
+        return 1
+    print("✅  smoke-quickstart: install → settings → decision_engine green")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/validate_decision_engine.py

@@ -0,0 +1,124 @@
+#!/usr/bin/env python3
+"""
+Decision-engine settings validator (road-to-productization P2).
+
+Walks every ``agent-settings.yml`` / ``agent-settings.template.yml``
+under the repo, parses any ``decision_engine`` block via the canonical
+``work_engine.scoring.decision_engine.parse`` schema, and surfaces:
+
+- hard errors → exit 1 (unknown keys, invalid enum values, bad types).
+- warnings    → exit 0 with a ``::warning::`` line per finding
+  (gates active but ``hooks.enabled`` is false → gates won't fire).
+
+Contract: ``docs/contracts/decision-engine-gates.md``. Wired into
+``task ci`` via ``taskfiles/ci-fast.yml`` so configuration drift is
+caught before a Decision Engine surprise lands in main.
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+try:
+    import yaml
+except ImportError:  # pragma: no cover — bootstrap guard
+    print("::error::PyYAML not installed; cannot validate decision_engine block")
+    sys.exit(3)
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+TEMPLATE_SCRIPTS = REPO_ROOT / ".agent-src.uncompressed" / "templates" / "scripts"
+if str(TEMPLATE_SCRIPTS) not in sys.path:
+    sys.path.insert(0, str(TEMPLATE_SCRIPTS))
+
+from work_engine.scoring.decision_engine import (  # noqa: E402
+    DecisionEngineConfigError,
+    parse,
+)
+
+# Files we always validate, even if they don't exist (template is
+# canonical — its absence is itself a regression).
+TEMPLATE_PATH = REPO_ROOT / "config" / "agent-settings.template.yml"
+# Project-level overrides developers may have on disk locally.
+LOCAL_PATHS = [REPO_ROOT / ".agent-settings.yml"]
+
+
+def _load_yaml(path: Path) -> dict | None:
+    if not path.is_file():
+        return None
+    try:
+        raw = yaml.safe_load(path.read_text(encoding="utf-8"))
+    except yaml.YAMLError as exc:
+        print(f"::error file={path}::malformed YAML: {exc}")
+        return {}
+    if raw is None:
+        return {}
+    if not isinstance(raw, dict):
+        print(f"::error file={path}::top-level must be a mapping")
+        return {}
+    return raw
+
+
+def _validate(path: Path, doc: dict) -> tuple[int, int]:
+    """Return ``(errors, warnings)`` counts for ``doc``."""
+    errors = 0
+    warnings = 0
+    block = doc.get("decision_engine")
+    if block is None:
+        return 0, 0
+    try:
+        settings = parse(block)
+    except DecisionEngineConfigError as exc:
+        rel = path.relative_to(REPO_ROOT)
+        print(f"::error file={rel}::decision_engine: {exc}")
+        return 1, 0
+    if settings.any_gate_active:
+        hooks_block = doc.get("hooks") or {}
+        if isinstance(hooks_block, dict) and hooks_block.get("enabled") is False:
+            rel = path.relative_to(REPO_ROOT)
+            print(
+                f"::warning file={rel}::decision_engine gates configured "
+                "(min_confidence/block_on_risk/require_memory_hits) but "
+                "hooks.enabled=false — gates will not fire. Either enable "
+                "hooks or remove the gate keys."
+            )
+            warnings += 1
+    return errors, warnings
+
+
+def main() -> int:
+    total_errors = 0
+    total_warnings = 0
+    paths: list[Path] = []
+    if TEMPLATE_PATH.is_file():
+        paths.append(TEMPLATE_PATH)
+    else:
+        print(f"::error file={TEMPLATE_PATH}::template missing")
+        return 1
+    for candidate in LOCAL_PATHS:
+        if candidate.is_file():
+            paths.append(candidate)
+    for path in paths:
+        doc = _load_yaml(path)
+        if doc is None:
+            continue
+        errors, warnings = _validate(path, doc)
+        total_errors += errors
+        total_warnings += warnings
+    if total_errors:
+        return 1
+    if total_warnings:
+        # Warnings already printed; CI treats exit 0 + ::warning:: as
+        # green-with-note. Surface a summary for human readers.
+        print(
+            f"decision_engine: {total_warnings} warning(s); see ::warning:: lines above"
+        )
+    return 0
+
+
+if __name__ == "__main__":
+    try:
+        sys.exit(main())
+    except Exception as exc:  # noqa: BLE001
+        print(f"::error::validate_decision_engine internal error: {exc}")
+        sys.exit(3)