agentbundle 0.2.0__py3-none-any.whl

agentbundle/commands/validate.py

@@ -0,0 +1,688 @@
+"""`agentbundle validate` subcommand.
+
+Validates a pack directory's ``pack.toml`` against ``pack.schema.json``,
+enforces the six-recipe enumeration, and applies the spec-version gate.
+With ``--strict``, runs conformance fixtures via the F-build render
+pipeline when they are present; warns and exits 0 when absent (v1 ship
+state — F-conformance deferred to v1.1 per RFC-0003).
+
+Exit codes:
+  0 — pack is schema-valid (and conformance fixtures pass if --strict).
+  1 — any schema error, unknown recipe, version mismatch, or conformance
+      failure; one-line stderr reason printed for each failure.
+
+Usage (wired by cli.py):
+    args.pack_path  — path to a pack directory containing pack.toml.
+    args.strict     — bool; run conformance fixtures when present.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+import tomllib
+from pathlib import Path
+
+from agentbundle.commands import _drop_warning
+from agentbundle.commands._common import check_spec_version_gate
+
+# Stdlib only — no third-party deps.
+
+# Six-recipe enumerated set from the sibling distribution-adapters spec.
+VALID_RECIPES: frozenset[str] = frozenset(
+    {
+        "per-pack-claude-plugin",
+        "per-pack-apm-package",
+        "marketplace",
+        "per-pack-overlay",
+        "composite-agents-md",
+        "composite-marketplace",
+    }
+)
+
+# Location of pack.schema.json relative to the repo root.  The schema is
+# bundled in docs/contracts/ and is also bundled at
+# agentbundle/_data/pack.schema.json for zipapp use.
+_HERE = Path(__file__).resolve().parent
+
+
+def _schema_path() -> Path:
+    """Locate pack.schema.json — bundled copy preferred, dev fallback."""
+    bundled = _HERE.parent / "_data" / "pack.schema.json"
+    if bundled.exists():
+        return bundled
+    # Dev fallback: walk up from agentbundle/ package to repo root.
+    repo_root = _HERE.parent.parent.parent.parent
+    return repo_root / "docs" / "contracts" / "pack.schema.json"
+
+
+def _conformance_fixtures_dir() -> Path:
+    """Return the expected path for conformance fixtures."""
+    # packages/agentbundle/tests/fixtures/conformance/
+    pkg_root = _HERE.parent.parent.parent
+    return pkg_root / "tests" / "fixtures" / "conformance"
+
+
+def run(args) -> int:
+    """Entry point called by the CLI dispatcher. Returns exit code."""
+    pack_path = Path(args.pack_path)
+    strict: bool = getattr(args, "strict", False)
+
+    # ── 1. Locate and load pack.toml ──────────────────────────────────────
+    pack_toml_path = pack_path / "pack.toml"
+    if not pack_toml_path.exists():
+        print(
+            f"validate: pack.toml not found at {pack_toml_path}",
+            file=sys.stderr,
+        )
+        return 1
+
+    try:
+        raw_toml = pack_toml_path.read_text(encoding="utf-8")
+        pack_data = tomllib.loads(raw_toml)
+    except tomllib.TOMLDecodeError as exc:
+        print(
+            f"validate: pack.toml is not valid TOML: {exc}",
+            file=sys.stderr,
+        )
+        return 1
+
+    # ── 2. Spec-version gate ──────────────────────────────────────────────
+    gate = check_spec_version_gate(pack_data)
+    if gate is not None:
+        return gate
+
+    # ── 3. Schema validation ──────────────────────────────────────────────
+    schema_path = _schema_path()
+    if not schema_path.exists():
+        print(
+            f"validate: pack.schema.json not found at {schema_path}",
+            file=sys.stderr,
+        )
+        return 1
+
+    schema = json.loads(schema_path.read_text(encoding="utf-8"))
+
+    # Import validate_instance from F-build (library-first).
+    from agentbundle.build.validate import validate as validate_instance
+
+    errors = validate_instance(pack_data, schema)
+    if errors:
+        # RFC-0004 § *Install-scope dimension* names a specific stderr
+        # text for the cross-field invariant: `pack <name>: default-scope
+        # '<requested>' not in allowed-scopes <declared-set>`. The
+        # schema's `contains` failure on `$.pack.install.allowed-scopes`
+        # is the structural form of that violation; surface it with the
+        # spec-named text instead of the generic schema message so
+        # adopters get the actionable line.
+        if _is_default_scope_invariant_violation(pack_data, errors[0]):
+            pack_name = pack_data.get("pack", {}).get("name", pack_path.name)
+            install = pack_data.get("pack", {}).get("install", {})
+            requested = install.get("default-scope")
+            allowed = install.get("allowed-scopes", [])
+            print(
+                f"validate: pack {pack_name}: default-scope {requested!r} "
+                f"not in allowed-scopes {allowed}",
+                file=sys.stderr,
+            )
+            return 1
+        # One-line stderr: first error only (spec says "one-line reason").
+        print(
+            f"validate: schema error — {errors[0]}",
+            file=sys.stderr,
+        )
+        return 1
+
+    # ── 4. Recipe gate ────────────────────────────────────────────────────
+    recipes = _extract_recipes(pack_data)
+    for recipe in recipes:
+        if recipe not in VALID_RECIPES:
+            print(
+                f"validate: unknown recipe {recipe!r}; "
+                f"valid recipes are {sorted(VALID_RECIPES)}",
+                file=sys.stderr,
+            )
+            return 1
+
+    # ── 4a. Allowed-adapters cross-field check (RFC-0011 / AC3, AC22) ─────
+    # The schema admits `allowed-adapters` as `array<string>` but doesn't
+    # hardcode the adapter enum (it's contract-derived). Validate here:
+    #   - every entry must be in the bundled contract's shipped-adapter set;
+    #   - when "user" ∈ allowed-scopes, every entry must additionally be in
+    #     the user-scope-capable subset (declare an `[adapter.<name>.scope]`
+    #     table). The refuse-and-explain messages match the wording pinned
+    #     in spec § *Always do*.
+    aa_refusal = _validate_allowed_adapters(pack_data)
+    if aa_refusal is not None:
+        print(f"validate: pack.toml: {aa_refusal}", file=sys.stderr)
+        return 1
+
+    # ── 4b. User-scope refusal rails (RFC-0004 A/B/C) ─────────────────────
+    # Rails fire only when the pack declares "user" ∈ allowed-scopes. The
+    # rails run *after* schema validation so we know `[pack.install]`'s
+    # shape (when present) is well-formed before we read it. v0.1 packs
+    # have implied `allowed-scopes = ["repo"]`, so the rails are
+    # vacuously satisfied — `_allowed_scopes` returns `["repo"]` for
+    # them.
+    from agentbundle.build.scope_rails import run_all as run_scope_rails
+
+    allowed = _allowed_scopes(pack_data)
+    user_scope_hooks = _user_scope_hooks_opt_in(pack_data)
+    rail_refusal = run_scope_rails(pack_path, allowed, user_scope_hooks)
+    if rail_refusal is not None:
+        pack_name = (
+            pack_data.get("pack", {}).get("name") or pack_path.name
+        )
+        print(
+            f"validate: {pack_name}: {rail_refusal}",
+            file=sys.stderr,
+        )
+        return 1
+
+    # ── 4c/4d. Kiro hook-wiring rails (RFC-0005, T2 / T6) ────────────────
+    # Rails 4c (attach-to-agent) and 4d (event-vocabulary) are now merged
+    # into a single dispatch that swallows the compatibility-only refusals
+    # (missing attach-to-agent, out-of-vocab event) while preserving
+    # exit-1 for security (symlink) and correctness (parse-fail,
+    # unknown-agent) violations.
+    #
+    # Spec: docs/specs/incompatible-hook-event-drop AC1–AC5, AC6b.
+    from agentbundle.build.scope_rails import _load_pack_hook_wiring_safely
+
+    target_adapters = _kiro_target_adapters(pack_data, pack_path)
+    pack_name = pack_data.get("pack", {}).get("name") or pack_path.name
+
+    if "kiro" in target_adapters:
+        # 1. Safe-load: security + correctness refusals (AC3, AC3b, AC4).
+        loaded = _load_pack_hook_wiring_safely(pack_path, pack_name)
+        if isinstance(loaded, str):
+            print(f"validate: {loaded}", file=sys.stderr)
+            return 1
+        wiring_tomls, agent_basenames = loaded
+
+        # 2. Unknown-agent refusal (AC4b) — discriminated from input data,
+        #    NOT from inspecting check_kiro_attach_to_agent's refusal text,
+        #    which is bytewise identical for missing-vs-unknown subcases per
+        #    scope_rails.py:333-337 (load-bearing per round-2 review).
+        #
+        #    Condition: attach is not None AND is a string AND not in
+        #    agent_basenames — matches spec AC4b exactly.
+        #    Empty string is preserved as "unknown agent" (kept refusal,
+        #    exit 1) to match today's helper behavior at scope_rails.py:332
+        #    — `"" not in agent_basenames` is True, so today's helper
+        #    refuses on attach = ""; this spec preserves that.
+        for stem, body in sorted(wiring_tomls.items()):
+            attach = body.get("attach-to-agent") if isinstance(body, dict) else None
+            if (
+                attach is not None
+                and isinstance(attach, str)
+                and attach not in agent_basenames
+            ):
+                # Refusal text matches check_kiro_attach_to_agent's
+                # pinned wording byte-for-byte (RFC-0005:474). Single
+                # source of truth: the helper composes the same string;
+                # a future RFC-0005 wording change must update both.
+                refusal = (
+                    f"pack {pack_name}'s hook-wiring {stem}.toml "
+                    f"does not declare 'attach-to-agent' (or names an unknown "
+                    f"agent); required for kiro projection"
+                )
+                print(f"validate: {refusal}", file=sys.stderr)
+                return 1
+
+        # 3. Compatibility drops (missing-attach OR out-of-vocab event) —
+        #    flow to the shared enumerator + info-line emit. Single source
+        #    of truth with the install side (AC6b).
+        contract = _load_adapter_contract()
+        info_drops = _drop_warning.enumerate_event_dropped_wirings(
+            pack_path, "kiro", contract,
+        )
+        if info_drops:
+            info = _drop_warning.format_drop_message(
+                mode="validate_info",
+                pack_name=pack_name,
+                adapter="kiro",
+                dropped_counts={},
+                compatible_types=[],
+                event_drops=info_drops,
+            )
+            print(info)  # stdout per AC2 + adopter direction
+
+    # ── 4e. kiro-ide-hook validate rail (RFC-0005 v0.4, T-C2) ────────────
+    # Fires whenever the pack ships `.apm/kiro-ide-hooks/` content. The
+    # rail's `target_adapters` heuristic differs from `_kiro_target_adapters`
+    # — kiro-ide-hook needs no agent (file-event triggers fire
+    # independent of agent runtime; cf. § Pack-side schema), so a
+    # pack with kiro-ide-hooks but no `.apm/agents/` still targets
+    # kiro. Cheapest heuristic: presence of the source directory with
+    # at least one *.kiro.hook file.
+    if _dir_has_any_kiro_ide_hook(pack_path / ".apm" / "kiro-ide-hooks"):
+        from agentbundle.build.scope_rails import check_kiro_ide_hook
+
+        ide_event_vocab, ide_action_vocab = _kiro_ide_hook_vocabularies()
+        ide_hook_refusal = check_kiro_ide_hook(
+            pack_path=pack_path,
+            pack_name=pack_name,
+            target_adapters=("kiro", "kiro-ide"),  # "kiro" alias + canonical name
+            ide_event_vocabulary=ide_event_vocab,
+            ide_action_vocabulary=ide_action_vocab,
+        )
+        if ide_hook_refusal is not None:
+            print(f"validate: {ide_hook_refusal}", file=sys.stderr)
+            return 1
+
+    # ── 5. Strict / conformance mode ─────────────────────────────────────
+    if strict:
+        conformance_dir = _conformance_fixtures_dir()
+        if not conformance_dir.exists():
+            print(
+                "--strict conformance fixtures not present — skipping",
+                file=sys.stderr,
+            )
+            # Exit 0 on schema portion (v1 carve-out).
+            return 0
+        # Conformance fixtures present — run them.
+        rc = _run_conformance(pack_path, conformance_dir)
+        if rc != 0:
+            return rc
+
+    return 0
+
+
+def _is_default_scope_invariant_violation(pack_data: dict, first_error: str) -> bool:
+    """Return True when the first schema error is the cross-field invariant.
+
+    The schema's `if`/`then` block for `default-scope ∈ allowed-scopes`
+    surfaces as a `contains` failure on `$.pack.install.allowed-scopes`.
+    We also confirm the pack actually has the shape that triggered the
+    error (default-scope declared, allowed-scopes declared, default not
+    in allowed) so we don't mis-attribute an unrelated `contains`
+    failure to this rule.
+    """
+    install = pack_data.get("pack", {}).get("install")
+    if not isinstance(install, dict):
+        return False
+    default = install.get("default-scope")
+    allowed = install.get("allowed-scopes")
+    if not isinstance(default, str) or not isinstance(allowed, list):
+        return False
+    if default in allowed:
+        return False
+    # Match the validator's error path heuristically.
+    return (
+        "pack.install.allowed-scopes" in first_error
+        or "allowed-scopes" in first_error
+    )
+
+
+def _user_scope_hooks_opt_in(pack_data: dict) -> bool:
+    """Return True iff the pack declares ``[pack.install] user-scope-hooks = true``.
+
+    RFC-0005 § Rail B — user-scope lift: the flag is the consent
+    gesture that lets a pack ship hook-shaped primitives at user scope.
+    Absent or non-boolean → False (rail still refuses the pack).
+    """
+    pack = pack_data.get("pack", {})
+    if not isinstance(pack, dict):
+        return False
+    install = pack.get("install", {})
+    if not isinstance(install, dict):
+        return False
+    flag = install.get("user-scope-hooks")
+    return flag is True
+
+
+def _kiro_target_adapters(pack_data: dict, pack_path: Path) -> set[str]:
+    """Resolve the target-adapter set for the kiro hook-wiring rail.
+
+    Two paths:
+
+      - v0.6+ packs declaring ``allowed-adapters`` use the field as the
+        source of truth: ``"kiro" in allowed-adapters`` ⇒ ``{"kiro"}``,
+        else ``set()``. The rail is a no-op for v0.6+ packs that
+        deliberately exclude kiro.
+
+      - All other hook-wiring-capable contract versions (v0.3+, per
+        the ``contract_supports_hook_wiring`` predicate that replaces
+        the round-1 literal ``version != "0.3"`` gate) fall through
+        to on-disk inference: pack ships both ``.apm/agents/`` and
+        ``.apm/hook-wiring/`` ⇒ ``{"kiro"}``. Pre-hook-wiring
+        contracts (v0.1, v0.2) skip the rail.
+
+    Returns ``{"kiro"}`` when the rail should fire; empty set
+    (rail no-op) otherwise.
+    """
+    from agentbundle.scope import contract_supports_hook_wiring
+
+    pack = pack_data.get("pack", {})
+    if not isinstance(pack, dict):
+        return set()
+    contract = pack.get("adapter-contract")
+    if not isinstance(contract, dict):
+        return set()
+    version = contract.get("version")
+    if not contract_supports_hook_wiring(version):
+        return set()
+
+    # v0.6+ declarative early-return from allowed-adapters.
+    install = pack.get("install")
+    if isinstance(install, dict):
+        allowed = install.get("allowed-adapters")
+        if isinstance(allowed, list):
+            allowed_strs = [s for s in allowed if isinstance(s, str)]
+            return {"kiro"} if "kiro" in allowed_strs else set()
+
+    # Heuristic: kiro projection requires a same-pack agent. A pack
+    # with wiring but no agents has nothing to attach to.
+    agents_dir = pack_path / ".apm" / "agents"
+    wiring_dir = pack_path / ".apm" / "hook-wiring"
+    if not _dir_has_any_file(agents_dir, ".md"):
+        return set()
+    if not _dir_has_any_file(wiring_dir, ".toml"):
+        return set()
+    return {"kiro"}
+
+
+def _dir_has_any_file(directory: Path, suffix: str) -> bool:
+    """Return True if *directory* exists and contains at least one file
+    with *suffix*. Symlinks are ignored — the kiro rail consumes them
+    through `check_kiro_wiring`, which mirrors rail C's symlink refusal."""
+    if not directory.exists():
+        return False
+    for entry in directory.iterdir():
+        if entry.is_file() and entry.suffix == suffix:
+            return True
+    return False
+
+
+def _dir_has_any_kiro_ide_hook(directory: Path) -> bool:
+    """``.kiro.hook`` is a compound extension; ``Path.suffix`` only
+    returns ``.hook``, so the generic helper above misses it. A
+    dedicated check keeps the call site readable and pins the
+    compound-extension assumption in one place."""
+    if not directory.exists():
+        return False
+    for entry in directory.iterdir():
+        if entry.is_file() and entry.name.endswith(".kiro.hook"):
+            return True
+    return False
+
+
+def _kiro_ide_hook_vocabularies() -> tuple[list[str] | None, list[str] | None]:
+    """Resolve the kiro adapter's ``ide-event-vocabulary`` and
+    ``ide-action-vocabulary`` from the bundled contract.
+
+    Returns (None, None) when the contract pre-dates v0.4 (the
+    ``[adapter.kiro.projections.kiro-ide-hook]`` table doesn't exist),
+    which makes checks 2 and 3 of the validate rail no-ops — the
+    rail's checks 1 / 4 / 5 (required fields, malformed placeholder,
+    unresolvable placeholder) still fire because they're vocabulary-
+    independent.
+
+    Load-at-call-time discipline: the contract file is the source of
+    truth; no module-level cache so a test-time swap is visible
+    immediately.
+    """
+    from agentbundle.build.contract import load as load_contract
+
+    here = Path(__file__).resolve().parent
+    bundled = here.parent / "_data" / "adapter.toml"
+    if bundled.exists():
+        contract_path = bundled
+    else:
+        contract_path = here.parent.parent.parent.parent / "docs" / "contracts" / "adapter.toml"
+        if not contract_path.exists():
+            return None, None
+    contract = load_contract(contract_path)
+    adapters = contract.get("adapter", {})
+    # Prefer the kiro-ide block (v0.9+); fall back to kiro alias (pre-T1).
+    kiro = adapters.get("kiro-ide") or adapters.get("kiro") or {}
+    projections = kiro.get("projections", {}) if isinstance(kiro, dict) else {}
+    rule = projections.get("kiro-ide-hook", {}) if isinstance(projections, dict) else {}
+
+    def _as_string_list(value: object) -> list[str] | None:
+        if isinstance(value, list):
+            return [str(v) for v in value if isinstance(v, str)]
+        return None
+
+    return (
+        _as_string_list(rule.get("ide-event-vocabulary")) if isinstance(rule, dict) else None,
+        _as_string_list(rule.get("ide-action-vocabulary")) if isinstance(rule, dict) else None,
+    )
+
+
+def _load_adapter_contract() -> dict:
+    """Load the bundled adapter contract dict.
+
+    Same load-at-call-time discipline as
+    ``_kiro_ide_hook_vocabularies`` — the contract file is the source of
+    truth; no module-level cache so a test-time swap is visible.
+
+    Returns an empty dict when neither the bundled nor the dev-checkout
+    path exists (keeps the enumeration rail a no-op rather than crashing).
+    """
+    from agentbundle.build.contract import load as load_contract
+
+    here = Path(__file__).resolve().parent
+    bundled = here.parent / "_data" / "adapter.toml"
+    if bundled.exists():
+        contract_path = bundled
+    else:
+        contract_path = (
+            here.parent.parent.parent.parent / "docs" / "contracts" / "adapter.toml"
+        )
+        if not contract_path.exists():
+            return {}
+    return load_contract(contract_path)
+
+
+def _validate_allowed_adapters(pack_data: dict) -> str | None:
+    """Cross-field check for ``[pack.install] allowed-adapters``
+    (RFC-0011 substrate; RFC-0012 widens to fire at both scopes).
+
+    Returns None when the field is absent / valid; returns a
+    refuse-and-explain string suitable for printing under the
+    ``validate: pack.toml: ...`` prefix on violation. Reads the
+    bundled adapter contract for the shipped + user-scope-capable
+    sets; if the contract doesn't ship a value the pack declares,
+    that's the publisher-vs-installer drift case. **The shipped
+    check fires at both scopes** (RFC-0012); the user-scope-capability
+    subcheck is **scope-conditional** — fires only when the pack's
+    resolved scope is user (so a Copilot-bearing pack at
+    ``default-scope = "repo"`` admits cleanly).
+    """
+    import tomllib
+
+    from agentbundle.scope import (
+        shipped_adapters_from_contract,
+        user_scope_capable_adapters_from_contract,
+    )
+
+    pack = pack_data.get("pack", {})
+    if not isinstance(pack, dict):
+        return None
+    install = pack.get("install")
+    if not isinstance(install, dict):
+        return None
+    declared = install.get("allowed-adapters")
+    if not isinstance(declared, list):
+        return None
+    declared_strs = [s for s in declared if isinstance(s, str)]
+    if not declared_strs:
+        return None
+    if len(declared_strs) != len(set(declared_strs)):
+        return "[pack.install] allowed-adapters contains duplicate values"
+
+    shipped = shipped_adapters_from_contract()
+    user_capable = user_scope_capable_adapters_from_contract()
+    user_eligible = "user" in _allowed_scopes(pack_data)
+
+    for name in declared_strs:
+        if name not in shipped:
+            return (
+                f"[pack.install] allowed-adapters contains {name!r}, "
+                f"which is not a shipped adapter under the bundled "
+                f"contract"
+            )
+        if user_eligible and name not in user_capable:
+            # Read the bundled contract version once so the message
+            # tracks RFC-0012's v0.7 bump without per-spec edits.
+            from agentbundle.build.main import _read_bundled
+
+            cv = (
+                tomllib.loads(_read_bundled("adapter.toml"))
+                .get("contract", {})
+                .get("version", "?")
+            )
+            return (
+                f"[pack.install] allowed-adapters contains {name!r}, "
+                f"which does not declare a user-scope root in the v{cv} "
+                f"adapter contract"
+            )
+
+    return None
+
+
+def _allowed_scopes(pack_data: dict) -> list[str]:
+    """Return the pack's resolved allowed-scopes list.
+
+    Resolution mirrors RFC-0004 § *v0.1 vs v0.2 contract acceptance*:
+
+      - v0.1 packs (declared version "0.1", or no `[pack.adapter-contract]`)
+        get the implied `["repo"]`. Any stray `[pack.install]` table is
+        ignored.
+      - v0.2 packs read `[pack.install].allowed-scopes` when present; when
+        only `default-scope` is declared, the implied default is
+        `[default-scope]`.
+
+    The cross-field `default-scope ∈ allowed-scopes` invariant is owned
+    by the schema; we trust the schema's verdict here and only resolve
+    the list.
+    """
+    pack = pack_data.get("pack", {})
+    if not isinstance(pack, dict):
+        return ["repo"]
+    contract_version = (
+        pack.get("adapter-contract", {}).get("version")
+        if isinstance(pack.get("adapter-contract"), dict)
+        else None
+    )
+    # v0.2 introduced `[pack.install]`; v0.3 added `user-scope-hooks`;
+    # v0.6 added `allowed-adapters`. Treat any contract version >= 0.2
+    # as carrying the install table. The legacy v0.1 path (and any pack
+    # without an adapter-contract declaration) stays repo-only.
+    if contract_version is None or contract_version == "0.1":
+        return ["repo"]
+    install = pack.get("install", {})
+    if not isinstance(install, dict):
+        return ["repo"]
+    allowed = install.get("allowed-scopes")
+    if isinstance(allowed, list) and allowed:
+        return [s for s in allowed if isinstance(s, str)]
+    default = install.get("default-scope")
+    if isinstance(default, str):
+        return [default]
+    return ["repo"]
+
+
+def _extract_recipes(pack_data: dict) -> list[str]:
+    """Return the list of recipe names the pack declares, if any.
+
+    The schema allows a pack to declare recipes at ``[pack].recipes``
+    (a list of strings).  Returns an empty list if the field is absent or
+    the pack table is missing.
+    """
+    pack_table = pack_data.get("pack", {})
+    if not isinstance(pack_table, dict):
+        return []
+    recipes = pack_table.get("recipes", [])
+    if not isinstance(recipes, list):
+        return []
+    return [str(r) for r in recipes if isinstance(r, str)]
+
+
+def _run_conformance(pack_path: Path, conformance_dir: Path) -> int:
+    """Run each conformance fixture and assert the expected output tree.
+
+    Each fixture is a subdirectory under ``conformance_dir`` containing:
+      - ``expected/``  — the expected rendered output tree.
+
+    We call ``render.render_pack_to_dir`` and compare file trees.
+    Returns 0 if all fixtures pass; 1 on first mismatch (with stderr).
+    """
+    import tempfile
+
+    from agentbundle.render import render_pack_to_dir
+
+    fixture_dirs = sorted(
+        d for d in conformance_dir.iterdir() if d.is_dir()
+    )
+    if not fixture_dirs:
+        print(
+            "--strict: conformance directory present but empty — skipping",
+            file=sys.stderr,
+        )
+        return 0
+
+    for fixture in fixture_dirs:
+        expected_dir = fixture / "expected"
+        if not expected_dir.exists():
+            print(
+                f"--strict: fixture {fixture.name!r} has no expected/ tree; skipping",
+                file=sys.stderr,
+            )
+            continue
+
+        with tempfile.TemporaryDirectory() as raw:
+            actual_dir = Path(raw)
+            try:
+                render_pack_to_dir(pack_path, actual_dir)
+            except Exception as exc:
+                print(
+                    f"--strict: render failed for fixture {fixture.name!r}: {exc}",
+                    file=sys.stderr,
+                )
+                return 1
+
+            mismatch = _diff_trees(expected_dir, actual_dir)
+            if mismatch:
+                print(
+                    f"--strict: conformance failure in fixture {fixture.name!r}: "
+                    + mismatch,
+                    file=sys.stderr,
+                )
+                return 1
+
+    return 0
+
+
+def _diff_trees(expected: Path, actual: Path) -> str:
+    """Return a one-line description of the first difference, or '' if identical."""
+    expected_files = _tree_files(expected)
+    actual_files = _tree_files(actual)
+
+    only_in_expected = expected_files.keys() - actual_files.keys()
+    if only_in_expected:
+        first = sorted(only_in_expected)[0]
+        return f"file missing from actual: {first}"
+
+    only_in_actual = actual_files.keys() - expected_files.keys()
+    if only_in_actual:
+        first = sorted(only_in_actual)[0]
+        return f"unexpected file in actual: {first}"
+
+    for relpath in sorted(expected_files):
+        if expected_files[relpath] != actual_files[relpath]:
+            return f"content differs: {relpath}"
+
+    return ""
+
+
+def _tree_files(root: Path) -> dict[str, bytes]:
+    """Return all files under ``root`` as a dict of relpath → bytes."""
+    out: dict[str, bytes] = {}
+    for path in sorted(root.rglob("*")):
+        if path.is_file():
+            relpath = path.relative_to(root).as_posix()
+            out[relpath] = path.read_bytes()
+    return out