@event4u/agent-config 2.26.0 → 3.1.0

package/scripts/lint_artefact_frontmatter.py

@@ -0,0 +1,180 @@
+#!/usr/bin/env python3
+"""Lint Phase-4 discovery frontmatter on every artefact.
+
+Walks the same trees as `scripts/build_discovery_manifest.py` (skills,
+rules, commands, templates under `.agent-src.uncompressed/`) and asserts
+per-file that the five ADR-013 keys (`workspaces`, `packs`, `lifecycle`,
+`trust`, `install`) are present and well-formed:
+
+  - `workspaces:` exists, is a non-empty list, every value in `workspaces.yml`
+  - `packs:`      exists, is a non-empty list, every value in `packs.yml`
+  - `lifecycle:`  is one of {active, deprecated, experimental, archived}
+  - `trust.level` is one of {core, professional, experimental, advisory, restricted}
+  - `trust.confidence` is one of {high, medium, low}
+  - `trust.human_review_required` is a bool
+  - `install.default` and `install.removable` are bools
+  - artefact path is not also listed in `unassigned-artefacts.yml`
+
+Exits 0 clean, 1 on any violation. Stdlib + pyyaml. Cap: ≤ 200 LOC.
+"""
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+from typing import Any
+
+try:
+    import yaml
+except ImportError:  # pragma: no cover
+    print("ERROR: PyYAML required (pip install pyyaml)", file=sys.stderr)
+    sys.exit(2)
+
+ROOT = Path(__file__).resolve().parents[1]
+SRC = ROOT / ".agent-src.uncompressed"
+VOCAB_DIR = ROOT / "config" / "discovery"
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+from validate_frontmatter import parse_frontmatter  # noqa: E402
+
+LIFECYCLES = frozenset({"active", "deprecated", "experimental", "archived"})
+TRUST_LEVELS = frozenset(
+    {"core", "professional", "experimental", "advisory", "restricted"}
+)
+TRUST_CONFIDENCE = frozenset({"high", "medium", "low"})
+
+
+def _load_vocab() -> tuple[set[str], set[str], set[str]]:
+    ws = yaml.safe_load((VOCAB_DIR / "workspaces.yml").read_text("utf-8")) or []
+    packs = yaml.safe_load((VOCAB_DIR / "packs.yml").read_text("utf-8")) or []
+    raw_un = yaml.safe_load((VOCAB_DIR / "unassigned-artefacts.yml").read_text("utf-8")) or []
+    ws_ids = {e["id"] for e in ws}
+    pack_ids = {e["id"] for e in packs}
+    quarantine = {e["path"] for e in raw_un}
+    return ws_ids, pack_ids, quarantine
+
+
+def _iter_artefacts() -> list[Path]:
+    out: list[Path] = []
+    for p in sorted((SRC / "skills").rglob("SKILL.md")):
+        out.append(p)
+    for p in sorted((SRC / "rules").rglob("*.md")):
+        out.append(p)
+    for p in sorted((SRC / "commands").rglob("*.md")):
+        out.append(p)
+    if (SRC / "templates").exists():
+        for p in sorted((SRC / "templates").rglob("*.md")):
+            out.append(p)
+    return out
+
+
+def _check_one(
+    path: Path,
+    ws_ids: set[str],
+    pack_ids: set[str],
+    quarantine: set[str],
+) -> list[str]:
+    rel = path.relative_to(ROOT).as_posix()
+    errs: list[str] = []
+    if rel in quarantine:
+        # Quarantined scaffolds are not required to carry frontmatter and
+        # must NOT also try to (would shadow the materialisation contract).
+        text = path.read_text("utf-8", errors="replace")
+        fm, _ = parse_frontmatter(text)
+        if isinstance(fm, dict) and any(
+            k in fm for k in ("workspaces", "packs", "lifecycle", "trust", "install")
+        ):
+            errs.append(
+                f"{rel}: quarantined in unassigned-artefacts.yml but carries"
+                " discovery frontmatter — remove one or the other."
+            )
+        return errs
+
+    text = path.read_text("utf-8", errors="replace")
+    fm, _ = parse_frontmatter(text)
+    if not isinstance(fm, dict):
+        errs.append(f"{rel}: missing or unparseable frontmatter")
+        return errs
+
+    for key in ("workspaces", "packs", "lifecycle", "trust", "install"):
+        if key not in fm:
+            errs.append(f"{rel}: missing required key `{key}`")
+    if errs:
+        return errs
+
+    ws = fm["workspaces"]
+    if not isinstance(ws, list) or not ws:
+        errs.append(f"{rel}: workspaces must be a non-empty list")
+    else:
+        bad = [w for w in ws if w not in ws_ids]
+        if bad:
+            errs.append(f"{rel}: workspaces not in workspaces.yml: {bad}")
+
+    packs = fm["packs"]
+    if not isinstance(packs, list) or not packs:
+        errs.append(f"{rel}: packs must be a non-empty list")
+    else:
+        bad = [p for p in packs if p not in pack_ids]
+        if bad:
+            errs.append(f"{rel}: packs not in packs.yml: {bad}")
+
+    lc = fm["lifecycle"]
+    if lc not in LIFECYCLES:
+        errs.append(f"{rel}: lifecycle `{lc}` not in {sorted(LIFECYCLES)}")
+
+    trust = fm["trust"]
+    if not isinstance(trust, dict):
+        errs.append(f"{rel}: trust must be a mapping")
+    else:
+        if trust.get("level") not in TRUST_LEVELS:
+            errs.append(
+                f"{rel}: trust.level `{trust.get('level')}` not in {sorted(TRUST_LEVELS)}"
+            )
+        if trust.get("confidence") not in TRUST_CONFIDENCE:
+            errs.append(
+                f"{rel}: trust.confidence `{trust.get('confidence')}` not in"
+                f" {sorted(TRUST_CONFIDENCE)}"
+            )
+        if not isinstance(trust.get("human_review_required"), bool):
+            errs.append(f"{rel}: trust.human_review_required must be bool")
+
+    install = fm["install"]
+    if not isinstance(install, dict):
+        errs.append(f"{rel}: install must be a mapping")
+    else:
+        if not isinstance(install.get("default"), bool):
+            errs.append(f"{rel}: install.default must be bool")
+        if not isinstance(install.get("removable"), bool):
+            errs.append(f"{rel}: install.removable must be bool")
+    return errs
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    parser.add_argument("--quiet", action="store_true")
+    args = parser.parse_args(argv)
+
+    ws_ids, pack_ids, quarantine = _load_vocab()
+    artefacts = _iter_artefacts()
+    all_errs: list[str] = []
+    for p in artefacts:
+        all_errs.extend(_check_one(p, ws_ids, pack_ids, quarantine))
+
+    if all_errs:
+        for e in all_errs:
+            print(f"ERROR: {e}", file=sys.stderr)
+        print(
+            f"\n{len(all_errs)} violation(s) across {len(artefacts)} artefact(s).",
+            file=sys.stderr,
+        )
+        return 1
+    if not args.quiet:
+        print(
+            f"✅  lint-artefact-frontmatter: {len(artefacts)} artefact(s) clean"
+            f" (quarantine: {len(quarantine)})."
+        )
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/scripts/lint_bench_corpus.py

@@ -38,7 +38,13 @@ 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"
+
+# Live skill directories live under every artefact root post-monorepo
+# Phase 4 (legacy + packages/*/.agent-src.uncompressed/skills/).
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+from _lib.agent_src import artefact_roots  # noqa: E402
+
+SKILLS_DIRS = [root / "skills" for root in artefact_roots() if (root / "skills").is_dir()]
 
 VALID_CATEGORIES = frozenset({"canonical", "ambiguous", "destructive", "long-context"})
 # Non-dev corpus (pre-spec) uses legacy categories — accept them so the
@@ -51,7 +57,13 @@ FULL_COUNTS = {"canonical": 10, "ambiguous": 8, "destructive": 5, "long-context"
 
 
 def live_skills() -> set[str]:
-    return {p.name for p in SKILLS_DIR.iterdir() if p.is_dir() and (p / "SKILL.md").exists()}
+    slugs: set[str] = set()
+    for skills_dir in SKILLS_DIRS:
+        slugs.update(
+            p.name for p in skills_dir.iterdir()
+            if p.is_dir() and (p / "SKILL.md").exists()
+        )
+    return slugs
 
 
 def lint_corpus(path: Path, skills: set[str]) -> list[str]:

package/scripts/lint_command_tiers.py

@@ -19,7 +19,12 @@ from pathlib import Path
 QUIET = "--quiet" in sys.argv
 
 REPO = Path(__file__).resolve().parents[1]
-COMMANDS_DIR = REPO / ".agent-src.uncompressed" / "commands"
+
+# Commands live under every artefact root post-monorepo Phase 4.
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+from _lib.agent_src import artefact_roots  # noqa: E402
+
+COMMANDS_DIRS = [root / "commands" for root in artefact_roots() if (root / "commands").is_dir()]
 # Consumer-facing projection — must also carry tier so .augment/commands/
 # (which symlinks to .agent-src/commands/) renders the tier filter.
 COMMANDS_DIR_COMPRESSED = REPO / ".agent-src" / "commands"
@@ -102,7 +107,15 @@ def lint(commands_dir: Path, *, quiet: bool = False) -> int:
 
 
 def main() -> int:
-    rc = lint(COMMANDS_DIR, quiet=QUIET)
+    if not COMMANDS_DIRS:
+        print(
+            "lint_command_tiers: no commands dir found under any artefact root",
+            file=sys.stderr,
+        )
+        return 1
+    rc = 0
+    for commands_dir in COMMANDS_DIRS:
+        rc |= lint(commands_dir, quiet=QUIET)
     # The compressed projection is the consumer-facing tree (via the
     # .augment/commands → .agent-src/commands symlink). It must also
     # carry tier so the surface stays uniform.

package/scripts/lint_discovery_manifest.py

@@ -0,0 +1,136 @@
+#!/usr/bin/env python3
+"""Lint a generated discovery-manifest.json against schema + checksum.
+
+Checks:
+1. File parses as JSON.
+2. Validates against `docs/contracts/discovery-manifest.schema.json`.
+3. Recomputes sha256 with the `checksum` field zeroed and compares.
+4. Cross-references workspace / pack IDs against `config/discovery/*.yml`.
+
+CLI:
+  python scripts/lint_discovery_manifest.py [--manifest PATH]
+
+Exit codes:
+  0  clean
+  1  schema or integrity failure
+"""
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+try:
+    import jsonschema
+except ImportError:
+    print("error: jsonschema not installed (pip install jsonschema)", file=sys.stderr)
+    sys.exit(1)
+
+ROOT = Path(__file__).resolve().parents[1]
+SCHEMA_PATH = ROOT / "docs" / "contracts" / "discovery-manifest.schema.json"
+VOCAB_DIR = ROOT / "config" / "discovery"
+DEFAULT_MANIFEST = ROOT / "dist" / "discovery" / "discovery-manifest.json"
+
+
+def _serialize(manifest: dict[str, Any]) -> str:
+    return json.dumps(manifest, indent=2, sort_keys=True, ensure_ascii=False) + "\n"
+
+
+def _check_checksum(manifest: dict[str, Any]) -> str | None:
+    actual = manifest.get("checksum", "")
+    if not isinstance(actual, str) or not actual.startswith("sha256:"):
+        return f"checksum: malformed value {actual!r}"
+    # Mirror scripts/build_discovery_manifest.py::_finalise_checksum —
+    # `generated_at` is wall-clock and excluded from the digest input so
+    # the hash stays byte-stable across runs.
+    snapshot = dict(manifest)
+    snapshot["checksum"] = "sha256:" + "0" * 64
+    snapshot["generated_at"] = "<normalised>"
+    raw = _serialize(snapshot).encode("utf-8")
+    expected = "sha256:" + hashlib.sha256(raw).hexdigest()
+    if expected != actual:
+        return f"checksum mismatch: expected {expected}, got {actual}"
+    return None
+
+
+def _check_vocab(manifest: dict[str, Any]) -> list[str]:
+    errs: list[str] = []
+    workspaces = yaml.safe_load((VOCAB_DIR / "workspaces.yml").read_text(encoding="utf-8")) or []
+    packs = yaml.safe_load((VOCAB_DIR / "packs.yml").read_text(encoding="utf-8")) or []
+    ws_ids = {w["id"] for w in workspaces}
+    pack_ids = {p["id"] for p in packs}
+
+    m_ws_ids = {w["id"] for w in manifest.get("workspaces", [])}
+    m_pk_ids = {p["id"] for p in manifest.get("packs", [])}
+    if m_ws_ids != ws_ids:
+        diff = ws_ids ^ m_ws_ids
+        errs.append(f"workspaces: vocabulary/manifest mismatch on {sorted(diff)}")
+    if m_pk_ids != pack_ids:
+        diff = pack_ids ^ m_pk_ids
+        errs.append(f"packs: vocabulary/manifest mismatch on {sorted(diff)}")
+
+    for a in manifest.get("artefacts", []):
+        for w in a.get("workspaces", []):
+            if w not in ws_ids:
+                errs.append(f"{a['path']}: unknown workspace '{w}'")
+        for p in a.get("packs", []):
+            if p not in pack_ids:
+                errs.append(f"{a['path']}: unknown pack '{p}'")
+    return errs
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    parser.add_argument("--manifest", type=Path, default=DEFAULT_MANIFEST)
+    parser.add_argument("--quiet", action="store_true")
+    args = parser.parse_args(argv)
+
+    if not args.manifest.exists():
+        print(f"error: manifest not found at {args.manifest}", file=sys.stderr)
+        return 1
+
+    try:
+        manifest = json.loads(args.manifest.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as exc:
+        print(f"error: invalid JSON: {exc}", file=sys.stderr)
+        return 1
+
+    schema = json.loads(SCHEMA_PATH.read_text(encoding="utf-8"))
+    try:
+        jsonschema.validate(manifest, schema)
+    except jsonschema.ValidationError as exc:
+        print(f"schema error: {exc.message}", file=sys.stderr)
+        path = "/".join(str(p) for p in exc.absolute_path)
+        if path:
+            print(f"  at: {path}", file=sys.stderr)
+        return 1
+
+    if (err := _check_checksum(manifest)):
+        print(f"error: {err}", file=sys.stderr)
+        return 1
+
+    vocab_errs = _check_vocab(manifest)
+    if vocab_errs:
+        for e in vocab_errs[:20]:
+            print(f"error: {e}", file=sys.stderr)
+        if len(vocab_errs) > 20:
+            print(f"  ... and {len(vocab_errs) - 20} more", file=sys.stderr)
+        return 1
+
+    if not args.quiet:
+        print(
+            f"OK {args.manifest.relative_to(ROOT)}: "
+            f"{len(manifest['artefacts'])} artefacts, "
+            f"{len(manifest['unassigned'])} unassigned, "
+            f"checksum verified"
+        )
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/lint_discovery_vocabulary.py

@@ -0,0 +1,148 @@
+#!/usr/bin/env python3
+"""Vocabulary linter for `config/discovery/{workspaces,packs}.yml`.
+
+Source-of-truth check: the YAML files MUST mirror the closed vocabulary
+in `docs/decisions/ADR-013-discovery-frontmatter-contract.md` exactly.
+Cross-reference check: every default/optional pack id referenced from
+`workspaces.yml` MUST exist in `packs.yml`, and every workspace id in
+`packs.yml` MUST exist in `workspaces.yml`. Bidirectional integrity:
+every pack listed as a workspace's default/optional MUST list that
+workspace in its own `workspaces:` array (and vice versa).
+
+Non-overlap (ADR-010 alignment): no pack id may collide with a
+`cost_profile` value (minimal/balanced/full/custom) or a `profile.id`
+value (founder/developer/content_creator/agency/finance/ops).
+
+Cap: ≤ 150 LOC, stdlib + PyYAML. Exit 0 clean, 1 on failure.
+"""
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+from typing import Any
+
+try:
+    import yaml
+except ImportError:  # pragma: no cover
+    print("ERROR: PyYAML required (pip install pyyaml)", file=sys.stderr)
+    sys.exit(2)
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+WORKSPACES_YML = REPO_ROOT / "config" / "discovery" / "workspaces.yml"
+PACKS_YML = REPO_ROOT / "config" / "discovery" / "packs.yml"
+
+# Frozen ADR-013 vocabularies. Amendments require an ADR-013 edit + this list.
+ADR_WORKSPACES: frozenset[str] = frozenset({
+    "engineering", "product", "finance", "founder", "gtm", "ops",
+    "small-business", "construction", "agent-config-maintainer",
+})
+ADR_PACKS: frozenset[str] = frozenset({
+    "engineering-base", "php", "laravel", "symfony", "javascript",
+    "typescript", "react", "nextjs", "python", "product-basic",
+    "product-discovery", "finance-basic", "finance-advanced",
+    "gtm-sales", "gtm-marketing", "ops-people", "founder-strategy", "small-business",
+    "construction", "ai-video", "meta",
+})
+
+# ADR-010 non-overlap reservations.
+COST_PROFILE_RESERVED: frozenset[str] = frozenset({
+    "minimal", "balanced", "full", "custom",
+})
+PROFILE_ID_RESERVED: frozenset[str] = frozenset({
+    "founder", "developer", "content_creator", "agency", "finance", "ops",
+})
+
+
+def _load(path: Path) -> list[dict[str, Any]]:
+    if not path.exists():
+        raise SystemExit(f"ERROR: missing {path.relative_to(REPO_ROOT)}")
+    data = yaml.safe_load(path.read_text(encoding="utf-8")) or []
+    if not isinstance(data, list):
+        raise SystemExit(f"ERROR: {path.relative_to(REPO_ROOT)} must be a YAML list")
+    return data
+
+
+def lint(quiet: bool) -> int:
+    errors: list[str] = []
+    workspaces = _load(WORKSPACES_YML)
+    packs = _load(PACKS_YML)
+
+    ws_ids = {entry.get("id") for entry in workspaces}
+    pack_ids = {entry.get("id") for entry in packs}
+
+    # 1. ADR frozen-set parity.
+    missing_ws = ADR_WORKSPACES - ws_ids
+    extra_ws = ws_ids - ADR_WORKSPACES
+    if missing_ws:
+        errors.append(f"workspaces.yml missing ADR-013 ids: {sorted(missing_ws)}")
+    if extra_ws:
+        errors.append(f"workspaces.yml has ids not in ADR-013: {sorted(extra_ws)}")
+    missing_p = ADR_PACKS - pack_ids
+    extra_p = pack_ids - ADR_PACKS
+    if missing_p:
+        errors.append(f"packs.yml missing ADR-013 ids: {sorted(missing_p)}")
+    if extra_p:
+        errors.append(f"packs.yml has ids not in ADR-013: {sorted(extra_p)}")
+
+    # 2. Cross-reference: workspace default/optional packs → pack ids.
+    for ws in workspaces:
+        wid = ws.get("id")
+        for key in ("default_packs", "optional_packs"):
+            for pid in ws.get(key, []) or []:
+                if pid not in pack_ids:
+                    errors.append(f"workspaces.yml '{wid}'.{key} → unknown pack '{pid}'")
+
+    # 3. Cross-reference: pack workspaces → workspace ids.
+    for pk in packs:
+        pid = pk.get("id")
+        for wid in pk.get("workspaces", []) or []:
+            if wid not in ws_ids:
+                errors.append(f"packs.yml '{pid}'.workspaces → unknown workspace '{wid}'")
+        for hint in pk.get("requires_hint", []) or []:
+            if hint not in pack_ids:
+                errors.append(f"packs.yml '{pid}'.requires_hint → unknown pack '{hint}'")
+
+    # 4. Bidirectional integrity (council HIGH fold-in).
+    pack_by_id = {pk.get("id"): pk for pk in packs}
+    ws_by_id = {ws.get("id"): ws for ws in workspaces}
+    for ws in workspaces:
+        wid = ws.get("id")
+        for key in ("default_packs", "optional_packs"):
+            for pid in ws.get(key, []) or []:
+                pk = pack_by_id.get(pid)
+                if pk and wid not in (pk.get("workspaces") or []):
+                    errors.append(
+                        f"bidir: workspace '{wid}'.{key} lists '{pid}' but "
+                        f"pack '{pid}'.workspaces does not list '{wid}'"
+                    )
+    for pk in packs:
+        pid = pk.get("id")
+        for wid in pk.get("workspaces", []) or []:
+            ws = ws_by_id.get(wid)
+            if ws:
+                listed = set(ws.get("default_packs") or []) | set(ws.get("optional_packs") or [])
+                if pid not in listed:
+                    errors.append(
+                        f"bidir: pack '{pid}'.workspaces lists '{wid}' but "
+                        f"workspace '{wid}' does not list '{pid}' in default/optional_packs"
+                    )
+
+    # 5. Non-overlap (ADR-010).
+    overlap_cost = pack_ids & COST_PROFILE_RESERVED
+    if overlap_cost:
+        errors.append(f"pack ids collide with cost_profile values: {sorted(overlap_cost)}")
+    overlap_profile = pack_ids & PROFILE_ID_RESERVED
+    if overlap_profile:
+        errors.append(f"pack ids collide with profile.id values: {sorted(overlap_profile)}")
+
+    if errors:
+        for e in errors:
+            print(f"❌ {e}", file=sys.stderr)
+        return 1
+    if not quiet:
+        print(f"✅ discovery vocabulary OK — {len(ws_ids)} workspaces · {len(pack_ids)} packs")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(lint(quiet="--quiet" in sys.argv))

package/scripts/lint_explain_trace.py

@@ -0,0 +1,80 @@
+#!/usr/bin/env python3
+"""Lint an ExplainTrace v1 JSON payload against the schema.
+
+Reads a JSON file (or stdin via ``--stdin``) and validates it against
+``docs/contracts/explain-trace.schema.json``. Exit 0 on success,
+1 on validation failure, 2 on invocation error (missing schema, bad
+JSON). Used by Phase 4 unit tests; called from the
+``lint-explain-trace`` Taskfile target.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+import jsonschema
+
+
+def _repo_root() -> Path:
+    return Path(__file__).resolve().parent.parent
+
+
+def _load_schema() -> dict:
+    schema_path = _repo_root() / "docs" / "contracts" / "explain-trace.schema.json"
+    if not schema_path.exists():
+        print(f"❌  explain-trace schema not found at {schema_path}", file=sys.stderr)
+        raise SystemExit(2)
+    with schema_path.open("r", encoding="utf-8") as fh:
+        return json.load(fh)
+
+
+def _read_payload(path: str | None, *, from_stdin: bool) -> object:
+    if from_stdin:
+        try:
+            return json.load(sys.stdin)
+        except json.JSONDecodeError as exc:
+            print(f"❌  stdin is not valid JSON: {exc}", file=sys.stderr)
+            raise SystemExit(2) from exc
+    if path is None:
+        print("❌  pass a JSON file path or --stdin", file=sys.stderr)
+        raise SystemExit(2)
+    p = Path(path)
+    if not p.exists():
+        print(f"❌  trace file not found: {p}", file=sys.stderr)
+        raise SystemExit(2)
+    try:
+        with p.open("r", encoding="utf-8") as fh:
+            return json.load(fh)
+    except json.JSONDecodeError as exc:
+        print(f"❌  {p} is not valid JSON: {exc}", file=sys.stderr)
+        raise SystemExit(2) from exc
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="lint_explain_trace",
+        description="Validate an ExplainTrace v1 JSON payload against the schema.",
+    )
+    parser.add_argument("path", nargs="?", default=None, help="Path to a JSON trace file.")
+    parser.add_argument("--stdin", action="store_true", help="Read the trace from stdin.")
+    opts = parser.parse_args(argv)
+
+    schema = _load_schema()
+    jsonschema.Draft202012Validator.check_schema(schema)
+    payload = _read_payload(opts.path, from_stdin=opts.stdin)
+
+    validator = jsonschema.Draft202012Validator(schema)
+    errors = sorted(validator.iter_errors(payload), key=lambda e: list(e.absolute_path))
+    if errors:
+        for err in errors:
+            loc = "/".join(str(p) for p in err.absolute_path) or "<root>"
+            print(f"❌  {loc}: {err.message}", file=sys.stderr)
+        return 1
+    print("✅  explain-trace OK")
+    return 0
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())