@event4u/agent-config 5.6.1 → 5.8.0

package/scripts/smoke_quickstart.py

@@ -4,7 +4,7 @@
 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`.
+     `.agent-settings.yml` with the documented default `rule_loading_tier`.
   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/runtime/state/<id>.json`) is
@@ -61,23 +61,24 @@ def _check_installer_runs(tmpdir: Path) -> tuple[int, Path | None]:
             _fail(f"installer exited {result.returncode}\nstdout:\n{result.stdout}\nstderr:\n{result.stderr}"),
             None,
         )
-    settings = tmpdir / ".agent-settings.yml"
+    # ADR-038: installer writes the canonical settings file under agents/settings/.
+    settings = tmpdir / "agents" / "settings" / ".agent-settings.yml"
     if not settings.exists():
-        return _fail(".agent-settings.yml not written by installer"), None
+        return _fail("agents/settings/.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."""
+    """Step 2 — assert default rule_loading_tier 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")
+    profile = parsed.get("rule_loading_tier")
     if profile != EXPECTED_DEFAULT_PROFILE:
         return _fail(
-            f"cost_profile drift: docs/contracts/cost-profile-defaults.md "
+            f"rule_loading_tier drift: docs/contracts/rule-loading-tier-defaults.md "
             f"declares '{EXPECTED_DEFAULT_PROFILE}', settings has '{profile!r}'"
         )
     return 0

package/scripts/sync_agent_settings.py

@@ -85,12 +85,14 @@ def render_diff(old_text: str, new_text: str, path: str) -> str:
 
 def main(argv: list[str] | None = None) -> int:
     ap = argparse.ArgumentParser(description=__doc__)
-    ap.add_argument("--path", default=DEFAULT_SETTINGS,
-                    help=f"target settings file (default: ./{DEFAULT_SETTINGS})")
+    ap.add_argument("--path", default=None,
+                    help="target settings file (default: canonical "
+                         "agents/settings/.agent-settings.yml, falling back to "
+                         "a legacy repo-root .agent-settings.yml — ADR-038)")
     ap.add_argument("--template", default=str(DEFAULT_TEMPLATE),
                     help="path to the settings template")
     ap.add_argument("--profile", default=None,
-                    help="cost_profile preset (minimal|balanced|full). "
+                    help="rule_loading_tier preset (minimal|balanced|full). "
                          "Default: inferred from target, else 'minimal'")
     ap.add_argument("--profile-dir", default=str(DEFAULT_PROFILE_DIR),
                     help="directory containing profile .ini files")
@@ -102,13 +104,18 @@ def main(argv: list[str] | None = None) -> int:
                     help="suppress summary on success")
     args = ap.parse_args(argv)
 
-    target = Path(args.path)
+    target = (
+        Path(args.path) if args.path is not None
+        else _install._resolve_settings_read(Path.cwd())
+    )
     template_path = Path(args.template)
     profile_dir = Path(args.profile_dir)
 
     try:
         user_data = load_user(target)
-        profile = args.profile or str(user_data.get("cost_profile") or "minimal")
+        profile = args.profile or str(
+            user_data.get("rule_loading_tier") or user_data.get("cost_profile") or "minimal"
+        )
         if profile not in _install.SUPPORTED_PROFILES:
             print(f"error: unsupported profile {profile!r}", file=sys.stderr)
             return 2

package/scripts/validate_agent_settings.py

@@ -0,0 +1,124 @@
+#!/usr/bin/env python3
+"""Agent-settings schema validator (rule_loading_tier untangle, 2026-06-01).
+
+Validates ``config/agent-settings.template.yml`` and any local
+``.agent-settings.yml`` against
+``scripts/schemas/agent-settings.schema.json``. The schema is
+deliberately permissive (``additionalProperties: true`` everywhere) and
+only enum-constrains the value-bearing keys that have historically been
+overloaded with a foreign vocabulary — the root cause of the
+``rule_loading_tier`` / memory-cadence collision. Its job is to make a
+value-vocabulary collision a hard CI failure.
+
+Template placeholders (``__RULE_LOADING_TIER__``, ``__USER_TYPE__``) are
+substituted with their installer defaults before validation, mirroring
+``scripts/install.py``.
+
+Exit codes:
+- 0 — every checked file validates.
+- 1 — at least one schema violation (unknown enum value, wrong type).
+- 3 — bootstrap failure (missing dependency / schema file).
+
+Contract: docs/contracts/cost-profile-defaults.md +
+docs/contracts/memory-visibility-v1.md. Wired into ``task ci`` via
+``taskfiles/ci-fast.yml``.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+try:  # invocation-agnostic import (repo-root-on-path vs scripts-on-path)
+    from scripts._lib.agent_settings import project_settings_path
+except ModuleNotFoundError:  # pragma: no cover
+    from _lib.agent_settings import project_settings_path
+
+try:
+    import yaml
+except ImportError:  # pragma: no cover — bootstrap guard
+    print("::error::PyYAML not installed; cannot validate agent settings")
+    sys.exit(3)
+
+try:
+    import jsonschema
+except ImportError:  # pragma: no cover — bootstrap guard
+    print("::error::jsonschema not installed; cannot validate agent settings")
+    sys.exit(3)
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+SCHEMA_PATH = REPO_ROOT / "scripts" / "schemas" / "agent-settings.schema.json"
+TEMPLATE_PATH = REPO_ROOT / "config" / "agent-settings.template.yml"
+LOCAL_PATHS = [project_settings_path(REPO_ROOT)]
+
+# Installer-default substitutions, mirroring scripts/install.py so the
+# template validates as it would after a fresh `balanced` install.
+PLACEHOLDERS = {
+    "__RULE_LOADING_TIER__": "balanced",
+    "__USER_TYPE__": "",
+}
+
+
+def _load_yaml(path: Path, *, substitute: bool) -> dict | None:
+    if not path.is_file():
+        return None
+    text = path.read_text(encoding="utf-8")
+    if substitute:
+        for placeholder, value in PLACEHOLDERS.items():
+            text = text.replace(placeholder, value)
+    try:
+        raw = yaml.safe_load(text)
+    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, validator: jsonschema.Draft7Validator) -> int:
+    errors = sorted(validator.iter_errors(doc), key=lambda e: list(e.path))
+    if not errors:
+        return 0
+    for err in errors:
+        loc = ".".join(str(p) for p in err.path) or "<root>"
+        print(f"::error file={path}::{loc}: {err.message}")
+    return len(errors)
+
+
+def main() -> int:
+    if not SCHEMA_PATH.is_file():
+        print(f"::error::schema missing: {SCHEMA_PATH}")
+        return 3
+    schema = json.loads(SCHEMA_PATH.read_text(encoding="utf-8"))
+    validator = jsonschema.Draft7Validator(schema)
+
+    total_errors = 0
+    checked = 0
+
+    template = _load_yaml(TEMPLATE_PATH, substitute=True)
+    if template is None:
+        print(f"::error file={TEMPLATE_PATH}::template missing")
+        return 1
+    total_errors += _validate(TEMPLATE_PATH, template, validator)
+    checked += 1
+
+    for local in LOCAL_PATHS:
+        doc = _load_yaml(local, substitute=False)
+        if doc is None:
+            continue
+        total_errors += _validate(local, doc, validator)
+        checked += 1
+
+    if total_errors:
+        print(f"agent-settings schema: {total_errors} violation(s) across {checked} file(s)")
+        return 1
+    print(f"agent-settings schema: OK ({checked} file(s) validated)")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/validate_decision_engine.py

@@ -19,6 +19,10 @@ from __future__ import annotations
 
 import sys
 from pathlib import Path
+try:  # invocation-agnostic import (repo-root-on-path vs scripts-on-path)
+    from scripts._lib.agent_settings import project_settings_path
+except ModuleNotFoundError:  # pragma: no cover
+    from _lib.agent_settings import project_settings_path
 
 try:
     import yaml
@@ -48,7 +52,7 @@ from work_engine.scoring.decision_engine import (  # noqa: E402
 # 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"]
+LOCAL_PATHS = [project_settings_path(REPO_ROOT)]
 
 
 def _load_yaml(path: Path) -> dict | None:

package/templates/minimal/.agent-settings.yml

@@ -15,7 +15,7 @@
 # --- Cost profile ---
 # Master switch for which rule tiers load. Options: minimal | balanced | full.
 # `balanced` is the recommended default; flip to `minimal` for kernel-only.
-cost_profile: balanced
+rule_loading_tier: balanced
 
 # --- Version pin (opt-in) ---
 # Leave commented out to follow whatever `agent-config` is on $PATH (per D4).