@event4u/agent-config 2.18.0 → 2.20.0

package/scripts/bench_per_tool.py

@@ -0,0 +1,216 @@
+#!/usr/bin/env python3
+"""Per-tool projection-fidelity bench — step-4 Phase 4.
+
+Re-runs the keyword-overlap selection scorer against each projected
+tool surface and computes:
+
+    fidelity(tool) = selection_accuracy(tool) / selection_accuracy(reference)
+
+Reference = Augment projection (most complete per roadmap). Threshold
+for "fit for purpose" is >= 0.85.
+
+Surfaces:
+- `.augment/skills/`   skill projection      automated  (reference)
+- `.claude/skills/`    skill projection      automated
+- `.cursor/rules/`     rules-only            not_applicable (no skill projection)
+- `.windsurfrules`     single concatenated   not_applicable
+- `.clinerules/`       rules-only            not_applicable
+
+Usage:
+    python3 scripts/bench_per_tool.py --corpus dev
+    python3 scripts/bench_per_tool.py --corpus dev --json
+    python3 scripts/bench_per_tool.py --corpus dev --threshold 0.85
+"""
+
+from __future__ import annotations
+
+import argparse
+import datetime as dt
+import json
+import re
+import sys
+from pathlib import Path
+
+try:
+    import yaml
+except ImportError:
+    sys.stderr.write("error: PyYAML required (pip install pyyaml)\n")
+    sys.exit(2)
+
+# Reuse tokenization + ranking from the reference runner so the only
+# axis that changes between tools is the skill catalogue on disk.
+from bench_runner import rank_skills  # type: ignore  # noqa: E402
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+CORPUS_DIR = REPO_ROOT / "tests" / "eval"
+REPORTS_DIR = REPO_ROOT / "bench" / "reports"
+
+# tool_id -> (skills_root, kind). kind = "skills" | "rules_only" | "single_file".
+SURFACES: dict[str, tuple[Path, str]] = {
+    "augment": (REPO_ROOT / ".augment" / "skills", "skills"),
+    "claude":  (REPO_ROOT / ".claude" / "skills",  "skills"),
+    "cursor":  (REPO_ROOT / ".cursor" / "rules",   "rules_only"),
+    "cline":   (REPO_ROOT / ".clinerules",         "rules_only"),
+    "windsurf":(REPO_ROOT / ".windsurfrules",      "single_file"),
+}
+
+REFERENCE_TOOL = "augment"
+
+
+def load_descriptions(root: Path) -> dict[str, str]:
+    """Return {skill_name: 'name + description'} for SKILL.md files under root."""
+    out: dict[str, str] = {}
+    if not root.is_dir():
+        return out
+    for skill_dir in sorted(root.iterdir()):
+        skill_md = skill_dir / "SKILL.md"
+        if not skill_md.is_file():
+            continue
+        text = skill_md.read_text(encoding="utf-8")
+        m = re.search(r"^---\s*\n(.*?)\n---\s*\n", text, re.DOTALL)
+        if not m:
+            continue
+        try:
+            fm = yaml.safe_load(m.group(1)) or {}
+        except yaml.YAMLError:
+            continue
+        desc = fm.get("description") or ""
+        name = fm.get("name") or skill_dir.name
+        if desc:
+            out[name] = f"{name} {desc}"
+    return out
+
+
+def score_corpus(skills: dict[str, str], prompts: list[dict], top_k: int) -> dict:
+    hits = 0
+    per_prompt = []
+    for p in prompts:
+        ranked = rank_skills(p["prompt"], skills, top_k)
+        expected = set(p.get("expected_skills", []))
+        hit = bool(expected & set(ranked))
+        if hit:
+            hits += 1
+        per_prompt.append({"id": p["id"], "expected": sorted(expected),
+                           "ranked": ranked, "hit": hit})
+    n = len(prompts)
+    return {
+        "prompts_total": n,
+        "prompts_hit": hits,
+        "selection_accuracy": round(hits / n, 4) if n else 0.0,
+        "skill_count": len(skills),
+        "per_prompt": per_prompt,
+    }
+
+
+def evaluate(corpus_path: Path, top_k: int, threshold: float) -> dict:
+    corpus = yaml.safe_load(corpus_path.read_text(encoding="utf-8"))
+    prompts = corpus["prompts"]
+    results: dict[str, dict] = {}
+
+    for tool, (root, kind) in SURFACES.items():
+        if kind != "skills":
+            results[tool] = {
+                "status": "not_applicable",
+                "reason": f"surface is {kind}; no SKILL.md projection",
+                "path": str(root.relative_to(REPO_ROOT)),
+            }
+            continue
+        skills = load_descriptions(root)
+        if not skills:
+            results[tool] = {"status": "error", "reason": "no skills found",
+                             "path": str(root.relative_to(REPO_ROOT))}
+            continue
+        scored = score_corpus(skills, prompts, top_k)
+        scored["status"] = "ok"
+        scored["path"] = str(root.relative_to(REPO_ROOT))
+        results[tool] = scored
+
+    ref = results.get(REFERENCE_TOOL, {})
+    ref_acc = ref.get("selection_accuracy", 0.0) if ref.get("status") == "ok" else 0.0
+    below = []
+    for tool, r in results.items():
+        if r.get("status") != "ok":
+            continue
+        fidelity = (r["selection_accuracy"] / ref_acc) if ref_acc else 0.0
+        r["fidelity"] = round(fidelity, 4)
+        r["passed_threshold"] = fidelity >= threshold
+        if tool != REFERENCE_TOOL and not r["passed_threshold"]:
+            below.append(tool)
+
+    return {
+        "schema": "projection-fidelity-v1",
+        "generated_at": dt.datetime.now(dt.timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"),
+        "corpus_id": corpus["corpus_id"],
+        "top_k": top_k,
+        "threshold": threshold,
+        "reference_tool": REFERENCE_TOOL,
+        "reference_accuracy": ref_acc,
+        "tools": results,
+        "below_threshold": below,
+    }
+
+
+def render_markdown(summary: dict) -> str:
+    lines = [
+        f"# Projection fidelity — {summary['corpus_id']}",
+        "",
+        f"_Generated {summary['generated_at']} · top-K={summary['top_k']} · "
+        f"threshold={summary['threshold']:.2f} · reference=`{summary['reference_tool']}`_",
+        "",
+        "| tool | status | skills | accuracy | fidelity | pass |",
+        "|---|---|---:|---:|---:|---|",
+    ]
+    for tool, r in summary["tools"].items():
+        status = r.get("status", "?")
+        if status != "ok":
+            lines.append(f"| `{tool}` | {status} | — | — | — | — |")
+            continue
+        lines.append(
+            f"| `{tool}` | ok | {r['skill_count']} | "
+            f"{r['selection_accuracy']:.2%} | {r['fidelity']:.2f} | "
+            f"{'✅' if r['passed_threshold'] else '❌'} |"
+        )
+    if summary["below_threshold"]:
+        lines += ["", f"**Below threshold:** {', '.join(summary['below_threshold'])} "
+                  f"→ inspect `scripts/_lib/generate_tools.py` projection mapping."]
+    else:
+        lines += ["", "**All projections fit-for-purpose** (≥ threshold)."]
+    return "\n".join(lines) + "\n"
+
+
+def main(argv=None) -> int:
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--corpus", default="dev")
+    ap.add_argument("--top-k", type=int, default=3)
+    ap.add_argument("--threshold", type=float, default=0.85)
+    ap.add_argument("--json", action="store_true")
+    ap.add_argument("--write-report", action="store_true",
+                    help="emit bench/reports/<ts>-<corpus>-projection.{json,md}")
+    args = ap.parse_args(argv)
+
+    corpus_path = CORPUS_DIR / f"corpus-{args.corpus}.yaml"
+    if not corpus_path.is_file():
+        sys.stderr.write(f"error: corpus not found: {corpus_path}\n")
+        return 2
+
+    summary = evaluate(corpus_path, args.top_k, args.threshold)
+
+    if args.write_report:
+        REPORTS_DIR.mkdir(parents=True, exist_ok=True)
+        stamp = summary["generated_at"].replace(":", "-")
+        base = REPORTS_DIR / f"{stamp}-{args.corpus}-projection"
+        base.with_suffix(".json").write_text(json.dumps(summary, indent=2) + "\n")
+        base.with_suffix(".md").write_text(render_markdown(summary))
+        sys.stderr.write(f"wrote {base}.json + {base}.md\n")
+
+    if args.json:
+        print(json.dumps(summary, indent=2))
+    else:
+        print(render_markdown(summary))
+
+    return 1 if summary["below_threshold"] else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())
+

package/scripts/bench_run.py

@@ -0,0 +1,155 @@
+#!/usr/bin/env python3
+"""Bench orchestrator — step-4 measurement-and-benchmark Phase 2.
+
+Wraps the selection-accuracy baseline collector (`scripts/bench_runner.py`),
+captures token / cost data from `agents/cost-tracking/sessions.jsonl` if
+present (per ruflo pattern, external-findings § 2), runs structural
+quality assertions per prompt, and emits a versioned JSON + Markdown
+report under `bench/reports/` per
+`docs/contracts/benchmark-report-schema.md`.
+
+Usage:
+    python3 scripts/bench_run.py --corpus dev
+    python3 scripts/bench_run.py --corpus dev --top-k 3 --quiet
+    python3 scripts/bench_run.py --corpus dev --agent-output outputs.json
+"""
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+sys.path.insert(0, str(REPO_ROOT / "scripts"))
+
+from _lib import script_output  # type: ignore[import-not-found]  # noqa: E402
+from _lib.bench_cost import aggregate_sessions  # noqa: E402
+from _lib.bench_quality import score_corpus  # noqa: E402
+from _lib.bench_report import (  # noqa: E402
+    report_paths,
+    render_markdown,
+    utc_now_filename_stamp,
+    utc_now_iso,
+    write_json,
+    write_markdown,
+)
+from bench_runner import run_corpus  # noqa: E402
+
+try:
+    import yaml
+except ImportError:
+    script_output.error("error: PyYAML required (pip install pyyaml)")
+    sys.exit(2)
+
+BENCH_RUN_VERSION = "0.1.0"
+PRICING_PATH = REPO_ROOT / "bench" / "pricing.yaml"
+SESSIONS_JSONL = REPO_ROOT / "agents" / "cost-tracking" / "sessions.jsonl"
+REPORTS_DIR = REPO_ROOT / "bench" / "reports"
+CORPUS_DIR = REPO_ROOT / "tests" / "eval"
+BASELINE_COLLECTOR = REPO_ROOT / "scripts" / "bench_runner.py"
+
+
+def _baseline_sha_or_mtime() -> str:
+    try:
+        return f"mtime:{int(BASELINE_COLLECTOR.stat().st_mtime)}"
+    except OSError:
+        return "unavailable"
+
+
+def _verdict(selection: dict, quality: dict) -> dict[str, str]:
+    sel = "pass" if selection["passed"] else "fail"
+    if quality["source"] == "not_collected":
+        qual = "not_collected"
+        overall = "partial"
+    else:
+        qual = "pass" if quality["quality_score"] >= 0.60 else "fail"
+        overall = "pass" if (sel == "pass" and qual == "pass") else "fail"
+    return {"selection": sel, "quality": qual, "overall": overall}
+
+
+def build_report(
+    corpus_path: Path,
+    top_k: int,
+    agent_output: Path | None,
+) -> dict:
+    selection = run_corpus(corpus_path, top_k)
+    corpus_yaml = yaml.safe_load(corpus_path.read_text(encoding="utf-8"))
+    prompts = corpus_yaml.get("prompts", [])
+    cost = aggregate_sessions(SESSIONS_JSONL, PRICING_PATH)
+    quality = score_corpus(prompts, agent_output)
+    verdict = _verdict(selection, quality)
+    return {
+        "schema_version": 1,
+        "generated_at": utc_now_iso(),
+        "corpus": {
+            "id": selection["corpus_id"],
+            "path": str(corpus_path.relative_to(REPO_ROOT)),
+            "prompt_count": len(prompts),
+        },
+        "runner": {
+            "bench_run_version": BENCH_RUN_VERSION,
+            "baseline_collector": str(BASELINE_COLLECTOR.relative_to(REPO_ROOT)),
+            "baseline_collector_sha": _baseline_sha_or_mtime(),
+        },
+        "selection": selection,
+        "cost": cost,
+        "quality": quality,
+        "verdict": verdict,
+    }
+
+
+def main(argv: list[str] | None = None) -> int:
+    ap = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    ap.add_argument("--corpus", default="dev", help="corpus id (default: dev)")
+    ap.add_argument("--top-k", type=int, default=3)
+    ap.add_argument("--agent-output", type=Path, default=None,
+                    help="Path to JSON {id: output_text} for quality scoring (Phase 3)")
+    ap.add_argument("--quiet", action="store_true",
+                    help="Print only the report path + headline")
+    ap.add_argument("--stamp", default=None,
+                    help="Override timestamp (test hook); defaults to UTC now")
+    ap.add_argument("--no-write", action="store_true",
+                    help="Compute the report but do not write files (dry run)")
+    args = ap.parse_args(argv)
+
+    corpus_path = CORPUS_DIR / f"corpus-{args.corpus}.yaml"
+    if not corpus_path.is_file():
+        script_output.error(f"error: corpus not found: {corpus_path}")
+        return 2
+
+    report = build_report(corpus_path, args.top_k, args.agent_output)
+    stamp = args.stamp or utc_now_filename_stamp()
+    json_path, md_path = report_paths(REPORTS_DIR, report["corpus"]["id"], stamp)
+
+    if not args.no_write:
+        write_json(json_path, report)
+        write_markdown(md_path, report)
+
+    verdict = report["verdict"]
+    sel = report["selection"]
+    qual = report["quality"]
+    cost = report["cost"]
+    headline = (
+        f"bench {report['corpus']['id']} · "
+        f"selection {sel['selection_accuracy']:.2%} ({verdict['selection']}) · "
+        f"cost ${cost['totals']['total_cost_usd']:.6f} ({cost.get('source', 'n/a')}) · "
+        f"quality {qual['quality_score']:.2%} ({verdict['quality']}) · "
+        f"overall {verdict['overall']}"
+    )
+
+    if args.quiet:
+        print(headline)
+        if not args.no_write:
+            print(f"report: {md_path.relative_to(REPO_ROOT)}")
+    else:
+        print(render_markdown(report))
+        if not args.no_write:
+            print(f"\n→ json:     {json_path.relative_to(REPO_ROOT)}")
+            print(f"→ markdown: {md_path.relative_to(REPO_ROOT)}")
+
+    # Exit zero on overall pass OR partial (partial = quality_not_collected by design).
+    return 0 if verdict["overall"] in ("pass", "partial") else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))

package/scripts/compress.py

@@ -346,6 +346,7 @@ TOOL_DIRS = {
 SKILLS_SOURCE = PROJECT_ROOT / ".agent-src" / "skills"
 COMMANDS_SOURCE = PROJECT_ROOT / ".agent-src" / "commands"
 PERSONAS_SOURCE = PROJECT_ROOT / ".agent-src" / "personas"
+USER_TYPES_SOURCE = PROJECT_ROOT / ".agent-src" / "user-types"
 CLAUDE_SKILLS_DIR = PROJECT_ROOT / ".claude" / "skills"
 
 PERSONA_TOOL_DIRS = {
@@ -353,6 +354,11 @@ PERSONA_TOOL_DIRS = {
     ".cursor/personas": "../../.agent-src/personas",
 }
 
+USER_TYPE_TOOL_DIRS = {
+    ".claude/user-types": "../../.agent-src/user-types",
+    ".cursor/user-types": "../../.agent-src/user-types",
+}
+
 # Map tool-projection directories to the canonical tool ID used by
 # `.agent-tools.yml`. Directories not in this map are always emitted.
 _DIR_TOOL_ID = {
@@ -361,6 +367,8 @@ _DIR_TOOL_ID = {
     ".clinerules": "cline",
     ".claude/personas": "claude-code",
     ".cursor/personas": "cursor",
+    ".claude/user-types": "claude-code",
+    ".cursor/user-types": "cursor",
 }
 
 
@@ -901,6 +909,43 @@ def generate_persona_symlinks() -> int:
     return total
 
 
+def generate_user_type_symlinks() -> int:
+    """Create symlink directories for user-types (.claude/user-types/, .cursor/user-types/).
+
+    Symlinks each user-type .md file from .agent-src/user-types/ into tool-specific
+    directories. Excludes README.md and _template/ — those are authoring scaffolding,
+    not user-type lenses.
+    """
+    if not USER_TYPES_SOURCE.exists():
+        print("  ⚠️  .agent-src/user-types/ not found — skipping user-types")
+        return 0
+
+    user_types = sorted([
+        f.name for f in USER_TYPES_SOURCE.glob("*.md") if f.stem != "README"
+    ])
+    tool_dirs = _filter_tool_dirs(USER_TYPE_TOOL_DIRS)
+    total = 0
+    for tool_dir, rel_prefix in tool_dirs.items():
+        target_dir = PROJECT_ROOT / tool_dir
+        target_dir.mkdir(parents=True, exist_ok=True)
+
+        # Clean stale symlinks
+        for item in target_dir.iterdir():
+            if item.is_symlink() and item.name not in user_types and item.name != "README.md":
+                item.unlink()
+
+        for user_type in user_types:
+            link = target_dir / user_type
+            target = Path(rel_prefix) / user_type
+            if link.exists() or link.is_symlink():
+                link.unlink()
+            link.symlink_to(target)
+            total += 1
+
+    info(f"  ✅  Created {total} user-type symlinks across {len(tool_dirs)} tool directories ({len(user_types)} user-types each)")
+    return total
+
+
 def generate_tools() -> None:
     """Generate all tool-specific directories and files.
 
@@ -916,13 +961,14 @@ def generate_tools() -> None:
     skills = generate_claude_skills() if _tool_active("claude-code") else 0
     commands = generate_claude_commands() if _tool_active("claude-code") else 0
     personas = generate_persona_symlinks()
+    user_types = generate_user_type_symlinks()
     cursor_mdc = generate_cursor_mdc_rules() if _tool_active("cursor") else 0
     windsurf_modern = generate_windsurf_modern_rules() if _tool_active("windsurf") else 0
     cursor_cmds = generate_cursor_commands() if _tool_active("cursor") else 0
     windsurf_wf = generate_windsurf_workflows() if _tool_active("windsurf") else 0
     summary = (
         f"✅  generate-tools — rules={rules} skills={skills} "
-        f"commands={commands} personas={personas} "
+        f"commands={commands} personas={personas} user_types={user_types} "
         f"cursor_mdc={cursor_mdc} windsurf_rules={windsurf_modern} "
         f"cursor_commands={cursor_cmds} windsurf_workflows={windsurf_wf} "
         f"windsurfrules={windsurfrules}"
@@ -943,7 +989,7 @@ def generate_tools() -> None:
 # them to symlinks (everything else is always symlinked).
 
 # Subdirectories of .agent-src/ that map into .augment/ as symlinks.
-AUGMENT_SYMLINK_DIRS = ("skills", "commands", "guidelines", "personas", "templates", "contexts", "scripts")
+AUGMENT_SYMLINK_DIRS = ("skills", "commands", "guidelines", "personas", "user-types", "templates", "contexts", "scripts")
 # Top-level files to symlink into .augment/ (README, etc.)
 AUGMENT_SYMLINK_FILES = ("README.md",)
 

package/scripts/config/__init__.py

@@ -0,0 +1,9 @@
+"""Config-layer loaders (profile, preset, pack).
+
+Phase 1 of step-15 product refinement. Single home for the audience /
+governance / workflow axes introduced by
+:mod:`docs.contracts.profile-system`,
+:mod:`docs.contracts.config-presets`, and the upcoming workflow-packs
+contract. Loaders here are pure, read-only, lazy-PyYAML; they layer on
+top of :mod:`scripts._lib.agent_settings` for project-root anchoring.
+"""

package/scripts/config/presets.py

@@ -0,0 +1,206 @@
+"""Preset loader — step-15 Phase 1 item 4.
+
+Resolves the active ``preset.id`` and merged knob set from the chain
+documented in :mod:`docs.contracts.config-presets`. Pure, read-only,
+lazy-PyYAML.
+
+Resolution chain (last writer wins for any single knob):
+
+1. ``pack.preset_id`` — set ``preset.id`` (Phase 2; ``None`` until packs
+   land).
+2. ``profile.preset_id`` — set ``preset.id`` if not pack-set.
+3. ``preset.<id>.yml`` — fill all knobs from the seed file.
+4. ``.agent-settings.yml`` user keys under ``preset:`` — override per-knob.
+5. Environment variables (``AGENT_CONFIG_PRESET_*``) — override per-knob,
+   structured keys mapped from the schema (see :data:`ENV_KNOB_MAP`).
+6. Runtime CLI overrides — caller passes a flat ``runtime_overrides`` map.
+
+Profile-aware overlay is **not** done here — callers that need
+profile-specific reads of preset knobs (e.g. ``block_on_risk.code_paths``
+for ``developer`` vs ``block_on_risk.financial_paths`` for ``founder``)
+read the merged knob bag returned by :func:`resolve_preset`.
+"""
+from __future__ import annotations
+
+import logging
+import os
+from copy import deepcopy
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+PRESET_ID_ENV = "AGENT_CONFIG_PRESET_ID"
+SEED_PRESET_IDS: tuple[str, ...] = ("fast", "balanced", "strict")
+DEFAULT_PRESET_ID = "balanced"
+PRESETS_DIRNAME = ".agent-src.uncompressed/presets"
+
+SOURCE_PACK = "pack"
+SOURCE_PROFILE = "profile"
+SOURCE_USER = "user-settings"
+SOURCE_ENV = "env"
+SOURCE_RUNTIME = "runtime"
+SOURCE_DEFAULT = "default"
+
+ENV_KNOB_MAP: dict[str, tuple[str, ...]] = {
+    "AGENT_CONFIG_PRESET_COST_DAILY_MAX_USD": ("cost", "daily_max_usd"),
+    "AGENT_CONFIG_PRESET_COST_WEEKLY_MAX_USD": ("cost", "weekly_max_usd"),
+    "AGENT_CONFIG_PRESET_COST_MONTHLY_MAX_USD": ("cost", "monthly_max_usd"),
+    "AGENT_CONFIG_PRESET_MCP_PER_CALL_MAX_USD": ("mcp", "per_call_max_usd"),
+    "AGENT_CONFIG_PRESET_MCP_PER_SESSION_MAX_USD": ("mcp", "per_session_max_usd"),
+    "AGENT_CONFIG_PRESET_COUNCIL_CAP_PER_CONSULT_USD": (
+        "council",
+        "cap_per_consult_usd",
+    ),
+    "AGENT_CONFIG_PRESET_AUTONOMY_DEFAULT": ("autonomy", "default"),
+    "AGENT_CONFIG_PRESET_CONFIDENCE_MIN_BAND": ("confidence", "min_band"),
+}
+
+
+@dataclass(frozen=True)
+class ResolvedPreset:
+    """Outcome of :func:`resolve_preset`. See config-presets contract."""
+
+    id: str
+    knobs: dict[str, Any] = field(default_factory=dict)
+    source: str = SOURCE_DEFAULT
+    overrides: tuple[str, ...] = ()
+    warning: str | None = None
+
+
+class PresetError(Exception):
+    """Raised when a preset id is referenced but its YAML cannot load."""
+
+
+def _load_yaml(path: Path) -> dict[str, Any]:
+    try:
+        import yaml  # type: ignore[import-not-found]
+    except ImportError:
+        logger.info("PyYAML unavailable; preset %s returned empty", path)
+        return {}
+    try:
+        text = path.read_text(encoding="utf-8")
+    except OSError as exc:
+        logger.warning("preset read failed for %s: %s", path, exc)
+        return {}
+    try:
+        data = yaml.safe_load(text) or {}
+    except yaml.YAMLError as exc:
+        logger.warning("preset parse failed for %s: %s", path, exc)
+        return {}
+    return data if isinstance(data, dict) else {}
+
+
+def _preset_file(project_root: Path, preset_id: str) -> Path:
+    return project_root / PRESETS_DIRNAME / f"{preset_id}.yml"
+
+
+def _coerce_scalar(raw: str) -> Any:
+    try:
+        return int(raw)
+    except ValueError:
+        pass
+    try:
+        return float(raw)
+    except ValueError:
+        pass
+    if raw.lower() in {"true", "false"}:
+        return raw.lower() == "true"
+    return raw
+
+
+def _deep_merge(base: dict[str, Any], override: dict[str, Any]) -> list[str]:
+    """Merge ``override`` into ``base`` in place; return dotted-override paths."""
+    paths: list[str] = []
+
+    def walk(b: dict[str, Any], o: dict[str, Any], prefix: str) -> None:
+        for key, value in o.items():
+            dotted = f"{prefix}{key}"
+            if isinstance(value, dict) and isinstance(b.get(key), dict):
+                walk(b[key], value, f"{dotted}.")
+            else:
+                b[key] = deepcopy(value)
+                paths.append(dotted)
+
+    walk(base, override, "")
+    return paths
+
+
+def _pick_id(
+    pack_preset_id: str | None,
+    profile_preset_id: str | None,
+    user_settings: dict[str, Any],
+    runtime_id: str | None,
+) -> tuple[str | None, str]:
+    if runtime_id:
+        return runtime_id, SOURCE_RUNTIME
+    env_id = os.environ.get(PRESET_ID_ENV)
+    if env_id:
+        return env_id, SOURCE_ENV
+    block = user_settings.get("preset") if isinstance(user_settings, dict) else None
+    if isinstance(block, dict) and block.get("id"):
+        return str(block["id"]), SOURCE_USER
+    if pack_preset_id:
+        return pack_preset_id, SOURCE_PACK
+    if profile_preset_id:
+        return profile_preset_id, SOURCE_PROFILE
+    return None, SOURCE_DEFAULT
+
+
+def resolve_preset(
+    *,
+    project_root: Path,
+    user_settings: dict[str, Any] | None = None,
+    pack_preset_id: str | None = None,
+    profile_preset_id: str | None = None,
+    runtime_id: str | None = None,
+    runtime_overrides: dict[tuple[str, ...], Any] | None = None,
+) -> ResolvedPreset:
+    """Return the active :class:`ResolvedPreset` for the current session."""
+    settings = user_settings or {}
+    preset_id, source = _pick_id(
+        pack_preset_id, profile_preset_id, settings, runtime_id,
+    )
+    if preset_id is None:
+        preset_id = DEFAULT_PRESET_ID
+        source = SOURCE_DEFAULT
+    yaml_path = _preset_file(project_root, preset_id)
+    if not yaml_path.exists():
+        raise PresetError(
+            f"preset.id={preset_id!r} ({source}) but {yaml_path} not found",
+        )
+    raw = _load_yaml(yaml_path)
+    knobs = raw.get("preset") or {}
+    if not isinstance(knobs, dict):
+        raise PresetError(f"{yaml_path} has no top-level 'preset:' mapping")
+    knobs = deepcopy(knobs)
+    knobs.pop("id", None)
+    overrides: list[str] = []
+    user_block = settings.get("preset") if isinstance(settings.get("preset"), dict) else None
+    if isinstance(user_block, dict):
+        user_overrides = {k: v for k, v in user_block.items() if k != "id"}
+        if user_overrides:
+            overrides.extend(_deep_merge(knobs, user_overrides))
+    for env_key, path in ENV_KNOB_MAP.items():
+        raw_value = os.environ.get(env_key)
+        if raw_value is None:
+            continue
+        cursor = knobs
+        for part in path[:-1]:
+            cursor = cursor.setdefault(part, {})
+        cursor[path[-1]] = _coerce_scalar(raw_value)
+        overrides.append(".".join(path))
+    if runtime_overrides:
+        for path, value in runtime_overrides.items():
+            cursor = knobs
+            for part in path[:-1]:
+                cursor = cursor.setdefault(part, {})
+            cursor[path[-1]] = value
+            overrides.append(".".join(path))
+    return ResolvedPreset(
+        id=preset_id,
+        knobs=knobs,
+        source=source,
+        overrides=tuple(overrides),
+    )