@event4u/agent-config 2.18.0 → 2.20.0

package/scripts/config/profiles.py

@@ -0,0 +1,173 @@
+"""Profile loader — step-15 Phase 1 item 1.
+
+Resolves the active ``profile.id`` from the chain documented in
+:mod:`docs.contracts.profile-system` and returns a structured
+:class:`ResolvedProfile`. Pure, read-only, lazy-PyYAML.
+
+Resolution chain (last writer wins):
+
+1. Pack-supplied ``profile_id`` (Phase 2 item 7 — pack loader passes it
+   in via ``pack_profile_id``; ``None`` until packs land).
+2. ``.agent-settings.yml`` top-level ``profile.id`` (and any user
+   overrides for ``audience`` / ``defaults`` / ``surface``).
+3. Environment variable ``AGENT_CONFIG_PROFILE_ID``.
+4. Runtime CLI flag — caller passes ``runtime_id``.
+
+Falls back to ``developer`` **only** when no settings file exists yet
+(fresh install before ``/onboard``). With a settings file present but
+no ``profile`` block, the loader returns a structured warning state so
+``/onboard`` can surface "audience not yet picked".
+"""
+from __future__ import annotations
+
+import logging
+import os
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from scripts._lib import agent_settings
+
+logger = logging.getLogger(__name__)
+
+PROFILE_ID_ENV = "AGENT_CONFIG_PROFILE_ID"
+SEED_PROFILE_IDS: tuple[str, ...] = (
+    "founder",
+    "developer",
+    "content_creator",
+    "agency",
+    "finance",
+    "ops",
+)
+DEFAULT_PROFILE_ID = "developer"
+PROFILES_DIRNAME = ".agent-src.uncompressed/profiles"
+
+SOURCE_PACK = "pack"
+SOURCE_USER = "user-settings"
+SOURCE_ENV = "env"
+SOURCE_RUNTIME = "runtime"
+SOURCE_DEFAULT = "default"
+SOURCE_MISSING = "missing"
+
+
+@dataclass(frozen=True)
+class ResolvedProfile:
+    """Outcome of :func:`resolve_profile`. See profile-system contract."""
+
+    id: str
+    audience: dict[str, str] = field(default_factory=dict)
+    preset_id: str | None = None
+    personas: tuple[str, ...] = ()
+    skills_hint: tuple[str, ...] = ()
+    commands_hint: tuple[str, ...] = ()
+    docs_first_pointer: str | None = None
+    source: str = SOURCE_DEFAULT
+    warning: str | None = None
+
+
+class ProfileError(Exception):
+    """Raised when a profile 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; profile %s returned empty", path)
+        return {}
+    try:
+        text = path.read_text(encoding="utf-8")
+    except OSError as exc:
+        logger.warning("profile read failed for %s: %s", path, exc)
+        return {}
+    try:
+        data = yaml.safe_load(text) or {}
+    except yaml.YAMLError as exc:
+        logger.warning("profile parse failed for %s: %s", path, exc)
+        return {}
+    return data if isinstance(data, dict) else {}
+
+
+def _profile_file(project_root: Path, profile_id: str) -> Path:
+    return project_root / PROFILES_DIRNAME / f"{profile_id}.yml"
+
+
+def _build_resolved(
+    profile_id: str,
+    raw: dict[str, Any],
+    *,
+    source: str,
+    warning: str | None = None,
+) -> ResolvedProfile:
+    block = raw.get("profile") or {}
+    audience_raw = block.get("audience") or {}
+    defaults = block.get("defaults") or {}
+    surface = block.get("surface") or {}
+    audience = {str(k): str(v) for k, v in audience_raw.items()}
+    personas = tuple(str(p) for p in (defaults.get("personas") or []))
+    skills_hint = tuple(str(s) for s in (defaults.get("skills_hint") or []))
+    commands_hint = tuple(str(c) for c in (surface.get("commands_hint") or []))
+    docs_pointer = surface.get("docs_first_pointer")
+    return ResolvedProfile(
+        id=profile_id,
+        audience=audience,
+        preset_id=defaults.get("preset_id"),
+        personas=personas,
+        skills_hint=skills_hint,
+        commands_hint=commands_hint,
+        docs_first_pointer=str(docs_pointer) if docs_pointer else None,
+        source=source,
+        warning=warning,
+    )
+
+
+def _pick_id(
+    pack_profile_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(PROFILE_ID_ENV)
+    if env_id:
+        return env_id, SOURCE_ENV
+    block = user_settings.get("profile") if isinstance(user_settings, dict) else None
+    if isinstance(block, dict) and block.get("id"):
+        return str(block["id"]), SOURCE_USER
+    if pack_profile_id:
+        return pack_profile_id, SOURCE_PACK
+    return None, SOURCE_MISSING
+
+
+def resolve_profile(
+    *,
+    project_root: Path,
+    user_settings: dict[str, Any] | None = None,
+    pack_profile_id: str | None = None,
+    runtime_id: str | None = None,
+) -> ResolvedProfile:
+    """Return the active :class:`ResolvedProfile` for the current session."""
+    settings = user_settings or {}
+    settings_file = project_root / agent_settings.DEFAULT_PROJECT_FILE
+    profile_id, source = _pick_id(pack_profile_id, settings, runtime_id)
+    if profile_id is None:
+        if settings_file.exists():
+            return ResolvedProfile(
+                id=DEFAULT_PROFILE_ID,
+                source=SOURCE_MISSING,
+                warning=(
+                    "no profile.id in .agent-settings.yml — run /onboard to "
+                    "pick an audience deliberately"
+                ),
+            )
+        return _build_resolved(
+            DEFAULT_PROFILE_ID,
+            _load_yaml(_profile_file(project_root, DEFAULT_PROFILE_ID)),
+            source=SOURCE_DEFAULT,
+        )
+    yaml_path = _profile_file(project_root, profile_id)
+    if not yaml_path.exists():
+        raise ProfileError(
+            f"profile.id={profile_id!r} ({source}) but {yaml_path} not found",
+        )
+    return _build_resolved(profile_id, _load_yaml(yaml_path), source=source)

package/scripts/cost/budget.mjs

@@ -14,10 +14,62 @@ import { dirname } from 'node:path';
 
 const STORE = process.env.BUDGET_STORE || 'agents/cost-tracking/sessions.jsonl';
 const CONFIG = process.env.BUDGET_CONFIG || 'agents/cost-tracking/budget.json';
+const SETTINGS = process.env.AGENT_SETTINGS || '.agent-settings.yml';
+
+// Minimal YAML reader for the `cost:` block — avoids a yaml dep. Reads
+// only the keys this script needs (cost.budgets.{daily,weekly,monthly},
+// cost.enforcement) from the well-formed two-space-indent template.
+function loadSettingsCost() {
+  if (!existsSync(SETTINGS)) return null;
+  let inCost = false, inBudgets = false;
+  const out = { budgets: {}, enforcement: null };
+  for (const raw of readFileSync(SETTINGS, 'utf-8').split('\n')) {
+    const line = raw.replace(/\s+$/, '');
+    if (!line || line.startsWith('#')) continue;
+    if (/^[a-z_]+:/.test(line)) inCost = inBudgets = false;
+    if (line === 'cost:') { inCost = true; continue; }
+    if (!inCost) continue;
+    if (/^  budgets:/.test(line)) { inBudgets = true; continue; }
+    if (inBudgets && /^    [a-z]+:/.test(line)) {
+      const [k, v] = line.trim().split(':').map((s) => s.trim());
+      const n = parseFloat(v);
+      if (Number.isFinite(n) && n > 0) out.budgets[k] = n;
+      continue;
+    }
+    if (/^  enforcement:/.test(line)) {
+      out.enforcement = line.split(':')[1].trim().replace(/['"]/g, '');
+      inBudgets = false;
+    }
+  }
+  const hasAny = Object.keys(out.budgets).length || out.enforcement;
+  return hasAny ? out : null;
+}
 
 function loadConfig() {
+  // Settings file wins when it carries any cost.* values.
+  const fromSettings = loadSettingsCost();
+  if (fromSettings) {
+    const period = process.env.BUDGET_PERIOD || 'all';
+    const periodKey = ({ today: 'daily', week: 'weekly', month: 'monthly' })[period];
+    const budget_usd = periodKey ? fromSettings.budgets[periodKey] : (
+      fromSettings.budgets.monthly || fromSettings.budgets.weekly || fromSettings.budgets.daily
+    );
+    if (Number.isFinite(budget_usd) && budget_usd > 0) {
+      return {
+        budget_usd,
+        enforcement: fromSettings.enforcement || 'advisory',
+        source: 'agent-settings.yml',
+        setAt: null,
+      };
+    }
+  }
   if (!existsSync(CONFIG)) return null;
-  try { return JSON.parse(readFileSync(CONFIG, 'utf-8')); } catch { return null; }
+  try {
+    const cfg = JSON.parse(readFileSync(CONFIG, 'utf-8'));
+    cfg.source = cfg.source || 'budget.json';
+    cfg.enforcement = cfg.enforcement || 'advisory';
+    return cfg;
+  } catch { return null; }
 }
 
 function saveConfig(cfg) {
@@ -123,18 +175,27 @@ function cmdCheck() {
     threshold: alert.threshold,
     recommended_action: recommendedAction(alert.level),
     sessionCount: filtered.length,
+    enforcement: cfg.enforcement || 'advisory',
+    source: cfg.source || 'budget.json',
   };
-  if (process.env.BUDGET_QUIET === '1') return console.log(JSON.stringify(out));
-  console.log(`# Budget check (period: ${period})\n`);
-  console.log('| Metric | Value |\n|---|---:|');
-  console.log(`| Budget | $${cfg.budget_usd.toFixed(2)} |`);
-  console.log(`| Spent | $${totalSpend.toFixed(2)} |`);
-  console.log(`| Remaining | $${out.remaining_usd.toFixed(2)} |`);
-  console.log(`| Utilization | ${out.utilization_pct.toFixed(1)}% |`);
-  console.log(`| Sessions counted | ${filtered.length} |`);
-  console.log(`| **Alert** | **${alert.emoji} ${alert.level}** |`);
-  console.log(`\nAction: ${out.recommended_action}`);
-  if (alert.level === 'HARD_STOP') process.exit(1);
+  const hardStop = alert.level === 'HARD_STOP' && out.enforcement === 'hard-stop';
+  if (process.env.BUDGET_QUIET === '1') {
+    console.log(JSON.stringify(out));
+  } else {
+    console.log(`# Budget check (period: ${period})\n`);
+    console.log('| Metric | Value |\n|---|---:|');
+    console.log(`| Budget | $${cfg.budget_usd.toFixed(2)} |`);
+    console.log(`| Spent | $${totalSpend.toFixed(2)} |`);
+    console.log(`| Remaining | $${out.remaining_usd.toFixed(2)} |`);
+    console.log(`| Utilization | ${out.utilization_pct.toFixed(1)}% |`);
+    console.log(`| Sessions counted | ${filtered.length} |`);
+    console.log(`| **Alert** | **${alert.emoji} ${alert.level}** |`);
+    console.log(`| Enforcement | ${out.enforcement} (source: ${out.source}) |`);
+    console.log(`\nAction: ${out.recommended_action}`);
+  }
+  // Only fail closed when enforcement is hard-stop; advisory mode reports
+  // the breach but exits clean so wrappers keep working.
+  if (hardStop) process.exit(1);
 }
 
 function main() {

package/scripts/cost/preflight.mjs

@@ -0,0 +1,89 @@
+#!/usr/bin/env node
+// Cost preflight hook — process-entry gate per ADR docs/adrs/cost/0001-hard-stop-hook.md.
+//
+// Wraps scripts/cost/budget.mjs check. Reads cost.enforcement from
+// .agent-settings.yml. Exits non-zero only when:
+//   - enforcement: hard-stop, AND
+//   - level: HARD_STOP
+//
+// Default behaviour without any budget configured: exit 0 (fail-open).
+// Designed to be invoked by shell / CI wrappers BEFORE composing a
+// turn: `task cost:preflight` or `node scripts/cost/preflight.mjs`.
+
+import { spawnSync } from 'node:child_process';
+
+const QUIET = process.env.PREFLIGHT_QUIET === '1';
+
+function runBudgetCheck() {
+  const env = { ...process.env, BUDGET_QUIET: '1' };
+  const r = spawnSync('node', ['scripts/cost/budget.mjs', 'check'], { env, encoding: 'utf-8' });
+  if (r.error) return { ok: false, fatal: true, msg: String(r.error) };
+  const out = (r.stdout || '').trim();
+  if (!out) return { ok: true, unbudgeted: true };
+  // budget.mjs prints a single JSON line under BUDGET_QUIET=1 when a
+  // budget is set; otherwise it prints a no-budget plaintext notice.
+  if (!out.startsWith('{')) return { ok: true, unbudgeted: true };
+  try {
+    const data = JSON.parse(out);
+    // budget.mjs JSON shape carries `error: 'no budget configured'`
+    // when cost.budgets are all 0 / absent — treat as unbudgeted.
+    if (data.error || !Number.isFinite(data.budget_usd)) return { ok: true, unbudgeted: true };
+    return { ok: true, data, childExit: r.status ?? 0 };
+  } catch (e) {
+    return { ok: false, fatal: true, msg: `parse: ${e.message}`, raw: out };
+  }
+}
+
+function refuse(data) {
+  if (QUIET) {
+    console.log(JSON.stringify({
+      preflight: 'refused',
+      reason: 'cost-hard-stop',
+      level: data.level,
+      utilization_pct: data.utilization_pct,
+      budget_usd: data.budget_usd,
+      spent_usd: data.spent_usd,
+      enforcement: data.enforcement,
+      source: data.source,
+    }));
+    return;
+  }
+  console.error('# 🛑 Cost preflight — HARD STOP\n');
+  console.error('| Metric | Value |');
+  console.error('|---|---:|');
+  console.error(`| Budget | $${data.budget_usd.toFixed(2)} |`);
+  console.error(`| Spent | $${data.spent_usd.toFixed(2)} |`);
+  console.error(`| Utilization | ${data.utilization_pct.toFixed(1)}% |`);
+  console.error(`| Enforcement | ${data.enforcement} (source: ${data.source}) |`);
+  console.error('\nBypass (pick one — see docs/contracts/cost-enforcement.md):');
+  console.error('  1. Raise the budget: edit .agent-settings.yml § cost.budgets.<period>');
+  console.error('  2. Reset the ledger: node scripts/cost/track.mjs reset --confirm');
+  console.error('  3. Disable enforcement: set cost.enforcement: advisory');
+}
+
+function main() {
+  const r = runBudgetCheck();
+  if (!r.ok && r.fatal) {
+    // Fail-open on infra error — never block work because the hook itself broke.
+    if (!QUIET) console.error(`# cost-preflight: skipped (${r.msg})`);
+    process.exit(0);
+  }
+  if (r.unbudgeted) {
+    if (!QUIET) console.log('# cost-preflight: no budget configured — pass.');
+    process.exit(0);
+  }
+  const d = r.data;
+  const hardStop = d.level === 'HARD_STOP' && d.enforcement === 'hard-stop';
+  if (hardStop) {
+    refuse(d);
+    process.exit(1);
+  }
+  if (!QUIET) {
+    console.log(`# cost-preflight: ${d.level} (${d.utilization_pct.toFixed(1)}% of $${d.budget_usd.toFixed(2)}, enforcement=${d.enforcement})`);
+  } else {
+    console.log(JSON.stringify({ preflight: 'pass', level: d.level, enforcement: d.enforcement, utilization_pct: d.utilization_pct }));
+  }
+  process.exit(0);
+}
+
+main();

package/scripts/lint_archived_skills.py

@@ -0,0 +1,143 @@
+#!/usr/bin/env python3
+"""Lint archive notes under agents/archived-skills/.
+
+Enforces the contract from
+.agent-src.uncompressed/templates/skill-archive-note.md:
+
+  1. Every <slug>.md under agents/archived-skills/ has the six required
+     frontmatter fields with valid values.
+  2. `reason` is one of {unused, merged, superseded, deprecated}.
+  3. When `reason ∈ {merged, superseded}` the `replacement` slug exists
+     under .agent-src.uncompressed/skills/.
+  4. No archived slug still has a live SKILL.md (no zombies).
+  5. No live SKILL.md cites an archived slug as a router target in
+     its frontmatter `replaced_by:` field.
+
+Hooked into `task ci` via `task lint-archived-skills`. Passes cleanly
+against an empty agents/archived-skills/ (only README.md present).
+
+Exit codes:
+  0  contract holds
+  1  one or more violations
+"""
+from __future__ import annotations
+
+import re
+import sys
+from pathlib import Path
+
+QUIET = "--quiet" in sys.argv
+
+REPO = Path(__file__).resolve().parents[1]
+ARCHIVE_DIR = REPO / "agents" / "archived-skills"
+SKILLS_DIR = REPO / ".agent-src.uncompressed" / "skills"
+
+REQUIRED_FIELDS = ("slug", "archived_on", "last_seen_count", "reason", "replacement", "last_known_callers")
+VALID_REASONS = frozenset({"unused", "merged", "superseded", "deprecated"})
+DATE_RE = re.compile(r"^\d{4}-\d{2}-\d{2}$")
+
+
+def parse_frontmatter(text: str) -> dict[str, str] | None:
+    if not text.startswith("---\n"):
+        return None
+    end = text.find("\n---\n", 4)
+    if end == -1:
+        return None
+    fields: dict[str, str] = {}
+    for line in text[4:end].splitlines():
+        if ":" not in line or line.startswith(" ") or line.startswith("-"):
+            continue
+        k, _, v = line.partition(":")
+        fields[k.strip()] = v.strip().strip('"').strip("'")
+    return fields
+
+
+def archived_slugs() -> list[Path]:
+    return sorted(p for p in ARCHIVE_DIR.glob("*.md") if p.name != "README.md")
+
+
+def live_skill_slugs() -> set[str]:
+    return {p.name for p in SKILLS_DIR.iterdir() if p.is_dir() and (p / "SKILL.md").exists()}
+
+
+def main() -> int:
+    if not ARCHIVE_DIR.exists():
+        print(f"❌  lint_archived_skills: {ARCHIVE_DIR} missing", file=sys.stderr)
+        return 1
+
+    notes = archived_slugs()
+    live = live_skill_slugs()
+    errors: list[str] = []
+
+    archived_keys: set[str] = set()
+    for note in notes:
+        text = note.read_text(encoding="utf-8")
+        fm = parse_frontmatter(text)
+        slug_from_name = note.stem
+
+        if fm is None:
+            errors.append(f"{note.name}: missing or malformed frontmatter")
+            continue
+
+        missing = [f for f in REQUIRED_FIELDS if f not in fm]
+        if missing:
+            errors.append(f"{note.name}: missing required fields: {', '.join(missing)}")
+            continue
+
+        if fm["slug"] != slug_from_name:
+            errors.append(f"{note.name}: slug field '{fm['slug']}' != filename stem '{slug_from_name}'")
+
+        if not DATE_RE.match(fm["archived_on"]):
+            errors.append(f"{note.name}: archived_on '{fm['archived_on']}' is not YYYY-MM-DD")
+
+        if fm["reason"] not in VALID_REASONS:
+            errors.append(f"{note.name}: reason '{fm['reason']}' not in {sorted(VALID_REASONS)}")
+
+        try:
+            int(fm["last_seen_count"])
+        except ValueError:
+            errors.append(f"{note.name}: last_seen_count '{fm['last_seen_count']}' is not an integer")
+
+        replacement = fm["replacement"]
+        reason = fm["reason"]
+        if reason in {"merged", "superseded"}:
+            if replacement == "none" or not replacement:
+                errors.append(f"{note.name}: reason={reason} requires a replacement slug, got 'none'")
+            elif replacement not in live:
+                errors.append(f"{note.name}: replacement '{replacement}' not found under {SKILLS_DIR}")
+        elif reason in {"unused", "deprecated"}:
+            if replacement not in {"none", ""}:
+                if replacement not in live:
+                    errors.append(f"{note.name}: replacement '{replacement}' not found under {SKILLS_DIR}")
+
+        if fm["slug"] in live:
+            errors.append(f"{note.name}: slug '{fm['slug']}' still has a live SKILL.md (zombie)")
+
+        archived_keys.add(fm["slug"])
+
+    # Cross-check: live skills must not list an archived slug as replaced_by.
+    for skill_dir in sorted(SKILLS_DIR.iterdir()):
+        skill_md = skill_dir / "SKILL.md"
+        if not skill_md.exists():
+            continue
+        text = skill_md.read_text(encoding="utf-8")
+        fm = parse_frontmatter(text)
+        if fm is None:
+            continue
+        rb = fm.get("replaced_by", "").strip()
+        if rb and rb in archived_keys:
+            errors.append(f"{skill_dir.name}/SKILL.md: replaced_by '{rb}' points at an archived slug")
+
+    if errors:
+        print(f"❌  lint_archived_skills: {len(errors)} violation(s) across {len(notes)} note(s)", file=sys.stderr)
+        for e in errors:
+            print(f"    {e}", file=sys.stderr)
+        return 1
+
+    if not QUIET:
+        print(f"✅  lint_archived_skills: {len(notes)} archive note(s), contract holds")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/scripts/lint_bench_corpus.py

@@ -0,0 +1,161 @@
+#!/usr/bin/env python3
+"""Lint benchmark corpora under tests/eval/corpus-*.yaml.
+
+Enforces the contract from docs/contracts/benchmark-corpus-spec.md:
+  - Required top-level keys (version, corpus_id, prompts) present.
+  - version == 1.
+  - selection_accuracy_target in [0.0, 1.0].
+  - Per-prompt schema (id format, category enum, language enum,
+    expected_skills non-empty + referencing real skills, destructive
+    prompts carry expected_carve_outs, prompt text non-empty).
+  - No duplicate ids within a corpus.
+
+Hooked into `task ci` via `task lint-bench`. Step-4 Phase 1 Step 3.
+
+Exit codes:
+  0  contract holds across every corpus
+  1  one or more violations
+  2  invocation error (missing PyYAML, no corpora found)
+
+Flags:
+  --quiet            suppress per-file OK lines
+  --require-full     also enforce 25-prompt composition (10/8/5/2)
+"""
+from __future__ import annotations
+
+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)
+
+QUIET = "--quiet" in sys.argv
+REQUIRE_FULL = "--require-full" in sys.argv
+
+REPO = Path(__file__).resolve().parents[1]
+CORPUS_DIR = REPO / "tests" / "eval"
+SKILLS_DIR = REPO / ".agent-src.uncompressed" / "skills"
+
+VALID_CATEGORIES = frozenset({"canonical", "ambiguous", "destructive", "long-context"})
+# Non-dev corpus (pre-spec) uses legacy categories — accept them so the
+# new linter does not break that file. Migration is a follow-up.
+LEGACY_CATEGORIES = frozenset({"content", "consulting", "finance", "ops", "safety"})
+VALID_LANGUAGES = frozenset({"en", "de"})
+VALID_VERSIONS = frozenset({1})
+ID_RE = re.compile(r"^[a-z][a-z0-9-]*-\d{2}$")
+FULL_COUNTS = {"canonical": 10, "ambiguous": 8, "destructive": 5, "long-context": 2}
+
+
+def live_skills() -> set[str]:
+    return {p.name for p in SKILLS_DIR.iterdir() if p.is_dir() and (p / "SKILL.md").exists()}
+
+
+def lint_corpus(path: Path, skills: set[str]) -> list[str]:
+    errors: list[str] = []
+    try:
+        data = yaml.safe_load(path.read_text(encoding="utf-8"))
+    except yaml.YAMLError as exc:
+        return [f"{path.name}: yaml_parse_error: {exc}"]
+
+    if not isinstance(data, dict):
+        return [f"{path.name}: missing_top_level: corpus must be a mapping"]
+
+    for key in ("version", "corpus_id", "prompts"):
+        if key not in data:
+            errors.append(f"{path.name}: missing_top_level: {key}")
+
+    if data.get("version") not in VALID_VERSIONS:
+        errors.append(f"{path.name}: unsupported_version: {data.get('version')!r}")
+
+    target = data.get("selection_accuracy_target")
+    if target is not None and not (isinstance(target, (int, float)) and 0.0 <= target <= 1.0):
+        errors.append(f"{path.name}: target_out_of_range: {target!r}")
+
+    prompts = data.get("prompts") or []
+    if not isinstance(prompts, list):
+        return errors + [f"{path.name}: missing_top_level: prompts must be a list"]
+
+    seen_ids: set[str] = set()
+    bucket_counts: dict[str, int] = {}
+    is_legacy = data.get("corpus_id") == "non-dev"
+    for idx, p in enumerate(prompts):
+        loc = f"{path.name}:#{idx}"
+        if not isinstance(p, dict):
+            errors.append(f"{loc}: bad_prompt_shape")
+            continue
+        pid = p.get("id")
+        if not isinstance(pid, str) or not ID_RE.match(pid):
+            errors.append(f"{loc}: bad_id_format: {pid!r}")
+        elif pid in seen_ids:
+            errors.append(f"{loc}: duplicate_id: {pid}")
+        else:
+            seen_ids.add(pid)
+
+        cat = p.get("category")
+        if cat not in VALID_CATEGORIES and not (is_legacy and cat in LEGACY_CATEGORIES):
+            errors.append(f"{loc}: bad_category: {cat!r}")
+        bucket_counts[cat] = bucket_counts.get(cat, 0) + 1
+
+        lang = p.get("language", "en")
+        if lang not in VALID_LANGUAGES:
+            errors.append(f"{loc}: bad_language: {lang!r}")
+
+        prompt_text = p.get("prompt", "")
+        if not isinstance(prompt_text, str) or not prompt_text.strip():
+            errors.append(f"{loc}: empty_prompt")
+
+        expected = p.get("expected_skills") or []
+        if not isinstance(expected, list) or not expected:
+            errors.append(f"{loc}: empty_expected")
+        else:
+            for slug in expected:
+                if slug not in skills:
+                    errors.append(f"{loc}: unknown_skill: {slug}")
+
+        if cat == "destructive":
+            carve = p.get("expected_carve_outs") or []
+            if not isinstance(carve, list) or not carve:
+                errors.append(f"{loc}: missing_carve_out")
+
+    if REQUIRE_FULL and not is_legacy:
+        for bucket, want in FULL_COUNTS.items():
+            have = bucket_counts.get(bucket, 0)
+            if have != want:
+                errors.append(f"{path.name}: composition_drift: {bucket} have={have} want={want}")
+
+    return errors
+
+
+def main() -> int:
+    if not CORPUS_DIR.is_dir():
+        sys.stderr.write(f"error: corpus dir missing: {CORPUS_DIR}\n")
+        return 2
+    corpora = sorted(CORPUS_DIR.glob("corpus-*.yaml"))
+    if not corpora:
+        sys.stderr.write("error: no corpora found\n")
+        return 2
+
+    skills = live_skills()
+    all_errors: list[str] = []
+    for path in corpora:
+        errs = lint_corpus(path, skills)
+        if errs:
+            all_errors.extend(errs)
+        elif not QUIET:
+            print(f"✅  {path.name}: contract OK")
+
+    if all_errors:
+        for err in all_errors:
+            print(f"❌  {err}", file=sys.stderr)
+        return 1
+    if not QUIET:
+        print(f"✅  lint-bench: {len(corpora)} corpora clean")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())