commitguardian 0.1.0__py3-none-any.whl

commitguard/policies/defaults.py

@@ -0,0 +1,48 @@
+"""Built-in policy defaults.
+
+These are the secure defaults applied when a repository has no configuration,
+and the base that repository configuration overrides. Every rule a built-in
+detector can emit must appear here (enforced by tests); configuration may only
+reference IDs listed here.
+"""
+
+from types import MappingProxyType
+
+from commitguard.core.decision import Action
+from commitguard.policies.model import Policy, PolicySet
+
+_DEFAULTS: tuple[Policy, ...] = (
+    Policy(
+        id="ai_coauthor",
+        action=Action.BLOCK,
+        description="AI agent listed as a co-author (e.g. Co-authored-by trailer).",
+    ),
+    Policy(
+        id="ai_identity",
+        action=Action.BLOCK,
+        description="AI agent recorded as the commit author or committer.",
+    ),
+    Policy(
+        id="ai_trailer",
+        action=Action.BLOCK,
+        description="AI attribution in other trailers (e.g. Generated-by, Assisted-by).",
+    ),
+    Policy(
+        id="malformed_trailer",
+        action=Action.WARN,
+        description="Trailer-like line that does not parse (possible evasion attempt).",
+    ),
+    Policy(
+        id="bot_identity",
+        action=Action.WARN,
+        description="Automation or bot account as author, committer or co-author.",
+    ),
+)
+
+DEFAULT_POLICIES = MappingProxyType({policy.id: policy for policy in _DEFAULTS})
+KNOWN_POLICY_IDS = frozenset(DEFAULT_POLICIES)
+
+
+def default_policy_set() -> PolicySet:
+    """Return the built-in policy set."""
+    return PolicySet(DEFAULT_POLICIES)

commitguard/policies/evaluator.py

@@ -0,0 +1,66 @@
+"""Policy evaluation: :class:`DetectionResult` + :class:`PolicySet` -> :class:`Decision`.
+
+Evaluation rules (all fail closed):
+
+* finding for a rule with an enabled policy  -> that policy's action;
+* finding for a rule whose policy is disabled -> ALLOW (recorded, not hidden);
+* finding for a rule with **no** policy       -> BLOCK;
+* detector failure                            -> BLOCK (an incomplete scan
+  cannot prove the commit is clean);
+* the overall decision is the most restrictive individual action.
+"""
+
+from commitguard.core.decision import Action, Decision, Explanation
+from commitguard.core.result import DetectionResult
+from commitguard.policies.model import PolicySet
+
+
+class PolicyEvaluator:
+    """Apply a :class:`PolicySet` to scan results."""
+
+    def __init__(self, policies: PolicySet) -> None:
+        self._policies = policies
+
+    def evaluate(self, result: DetectionResult) -> Decision:
+        explanations: list[Explanation] = []
+
+        for finding in result.findings:
+            policy = self._policies.get(finding.rule_id)
+            if policy is None:
+                explanations.append(
+                    Explanation(
+                        action=Action.BLOCK,
+                        reason=f"no policy configured for rule {finding.rule_id!r}; failing closed",
+                        finding=finding,
+                    )
+                )
+            elif not policy.enabled:
+                explanations.append(
+                    Explanation(
+                        action=Action.ALLOW,
+                        reason=f"policy {policy.id!r} is disabled",
+                        policy_id=policy.id,
+                        finding=finding,
+                    )
+                )
+            else:
+                explanations.append(
+                    Explanation(
+                        action=policy.action,
+                        reason=f"policy {policy.id!r} action is {policy.action.value}",
+                        policy_id=policy.id,
+                        finding=finding,
+                    )
+                )
+
+        for failure in result.failures:
+            explanations.append(
+                Explanation(
+                    action=Action.BLOCK,
+                    reason=f"detector {failure.detector!r} did not complete; failing closed",
+                    failure=failure,
+                )
+            )
+
+        action = Action.most_restrictive([e.action for e in explanations])
+        return Decision(action=action, explanations=tuple(explanations))

commitguard/policies/governance.py

@@ -0,0 +1,498 @@
+"""Governed policy resolution: which policy applies to a repository, and why.
+
+The organization layer decides *what configuration applies*; the policy engine
+(:mod:`commitguard.policies.evaluator`) still decides *what a finding means*.
+This module is the pure part of that split: given the governance inputs for
+one repository (policy layers, approved exceptions, onboarding mode) and,
+at scan time, the repository's own ``.commitguard.yaml``, it builds the
+effective :class:`~commitguard.policies.model.PolicySet` together with the
+provenance of every rule. It performs no I/O and evaluates no findings.
+
+Precedence, per rule (later steps win, subject to their own limits)::
+
+    1. built-in default                     rules/policies/defaults.py
+    2. organization policy  - default       replaced by a narrower default below
+    3. repository group     - default       several groups: the most restrictive
+    4. repository policy    - default       (set in the dashboard for one repository)
+    5. repository configuration             .commitguard.yaml at the trusted revision
+    6. mandatory requirements (floor)       the most restrictive mandatory entry of the
+                                            service, organization, group and repository
+                                            policies; nothing above can weaken it
+    7. approved exception                   the only way below a floor; scoped, expiring,
+                                            the most specific scope applies
+    8. monitor mode                         block is reported as warn (report only)
+
+Two strengths exist. A **mandatory** entry (``warn`` or ``block``) is a floor:
+lower layers may make the rule stricter but never weaker, and a lower layer
+that asks for less is recorded as a :class:`PolicyConflict` - never silently
+dropped. A **default** entry is a baseline that narrower layers and the
+repository configuration may replace in either direction. A rule no layer
+mentions is decided by the repository configuration (or the built-in default).
+
+Exceptions never add or remove detection: a finding under an exception is still
+recorded, with the lowered action and the exception that lowered it.
+"""
+
+import json
+from collections.abc import Iterable, Mapping, Sequence
+from datetime import datetime
+from enum import StrEnum
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator
+
+from commitguard.config.schema import CommitGuardConfig, PolicyOverride
+from commitguard.core.decision import Action
+from commitguard.policies.defaults import DEFAULT_POLICIES
+from commitguard.policies.loader import build_policy_set
+from commitguard.policies.mandatory import apply_mandatory_policies
+from commitguard.policies.model import Policy, PolicySet
+from commitguard.security.hashing import fingerprint, sha256_hex
+
+_STRICT = ConfigDict(frozen=True, extra="forbid")
+
+#: Limits on governance inputs (resource exhaustion protection).
+MAX_LAYERS = 64
+MAX_EXCEPTIONS = 256
+MAX_LABEL_CHARS = 200
+
+
+class Enforcement(StrEnum):
+    """How strongly a policy layer requires an action."""
+
+    MANDATORY = "mandatory"  # a floor: nothing below may weaken it
+    DEFAULT = "default"  # a baseline: narrower layers may replace it
+
+
+class PolicyLevel(StrEnum):
+    BUILT_IN = "built_in"
+    SERVICE = "service"
+    ORGANIZATION = "organization"
+    GROUP = "group"
+    REPOSITORY_POLICY = "repository_policy"
+    REPOSITORY_CONFIGURATION = "repository_configuration"
+    EXCEPTION = "exception"
+    MONITOR_MODE = "monitor_mode"
+
+
+#: Order used to break ties between floors of equal strength (broadest first).
+_LEVEL_ORDER = {
+    PolicyLevel.SERVICE: 0,
+    PolicyLevel.ORGANIZATION: 1,
+    PolicyLevel.GROUP: 2,
+    PolicyLevel.REPOSITORY_POLICY: 3,
+}
+LAYER_LEVELS = frozenset(_LEVEL_ORDER)
+
+
+class RepositoryMode(StrEnum):
+    ENFORCE = "enforce"
+    MONITOR = "monitor"
+
+
+class ExceptionScope(StrEnum):
+    ORGANIZATION = "organization"
+    GROUP = "group"
+    REPOSITORY = "repository"
+
+
+_SCOPE_SPECIFICITY = {
+    ExceptionScope.REPOSITORY: 2,
+    ExceptionScope.GROUP: 1,
+    ExceptionScope.ORGANIZATION: 0,
+}
+
+
+class RuleRequirement(BaseModel):
+    """One layer's requirement for one rule."""
+
+    model_config = _STRICT
+
+    action: Action
+    enforcement: Enforcement = Enforcement.MANDATORY
+
+    @model_validator(mode="after")
+    def _floor_actions(self) -> "RuleRequirement":
+        if self.enforcement is Enforcement.MANDATORY and self.action is Action.ALLOW:
+            raise ValueError("a mandatory requirement must be warn or block")
+        return self
+
+
+def validate_rule_ids(rules: Iterable[str]) -> None:
+    unknown = sorted(set(rules) - set(DEFAULT_POLICIES))
+    if unknown:
+        raise ValueError(f"unknown policy id(s): {', '.join(unknown)}")
+
+
+class PolicyLayer(BaseModel):
+    """A published policy version that applies to the repository."""
+
+    model_config = _STRICT
+
+    level: PolicyLevel
+    source_id: str = Field(default="", max_length=64)  # group ID or repository ID
+    label: str = Field(min_length=1, max_length=MAX_LABEL_CHARS)
+    version: int | None = Field(default=None, ge=1)
+    rules: dict[str, RuleRequirement] = {}
+
+    @field_validator("level")
+    @classmethod
+    def _layer_level(cls, value: PolicyLevel) -> PolicyLevel:
+        if value not in LAYER_LEVELS:
+            raise ValueError(f"{value.value} is not a policy layer")
+        return value
+
+    @field_validator("rules")
+    @classmethod
+    def _known(cls, value: dict[str, RuleRequirement]) -> dict[str, RuleRequirement]:
+        validate_rule_ids(value)
+        return value
+
+
+class ExceptionGrant(BaseModel):
+    """An approved, active exception as seen by the resolver."""
+
+    model_config = _STRICT
+
+    exception_id: str = Field(min_length=1, max_length=64)
+    rule_id: str
+    action: Action
+    scope: ExceptionScope
+    scope_label: str = Field(min_length=1, max_length=MAX_LABEL_CHARS)
+    expires_at: datetime | None = None  # None only for a documented permanent exception
+
+    @field_validator("rule_id")
+    @classmethod
+    def _known(cls, value: str) -> str:
+        validate_rule_ids([value])
+        return value
+
+    @field_validator("action")
+    @classmethod
+    def _lowering(cls, value: Action) -> Action:
+        if value is Action.BLOCK:
+            raise ValueError("an exception lowers enforcement to warn or allow")
+        return value
+
+
+class GovernanceInputs(BaseModel):
+    """Everything the organization layer decides for one repository."""
+
+    model_config = _STRICT
+
+    layers: tuple[PolicyLayer, ...] = ()
+    exceptions: tuple[ExceptionGrant, ...] = ()
+    mode: RepositoryMode = RepositoryMode.ENFORCE
+
+    @field_validator("layers")
+    @classmethod
+    def _bounded_layers(cls, value: tuple[PolicyLayer, ...]) -> tuple[PolicyLayer, ...]:
+        if len(value) > MAX_LAYERS:
+            raise ValueError(f"more than {MAX_LAYERS} policy layers")
+        return value
+
+    @field_validator("exceptions")
+    @classmethod
+    def _bounded_exceptions(cls, value: tuple[ExceptionGrant, ...]) -> tuple[ExceptionGrant, ...]:
+        if len(value) > MAX_EXCEPTIONS:
+            raise ValueError(f"more than {MAX_EXCEPTIONS} exceptions")
+        return value
+
+    @property
+    def empty(self) -> bool:
+        return not self.layers and not self.exceptions and self.mode is RepositoryMode.ENFORCE
+
+    def canonical(self) -> str:
+        """Deterministic JSON of the inputs that affect enforcement (labels excluded)."""
+        ordered = sorted(self.layers, key=lambda item: (_LEVEL_ORDER[item.level], item.source_id))
+        document = {
+            "layers": [
+                {
+                    "level": layer.level.value,
+                    "source": layer.source_id,
+                    "version": layer.version,
+                    "rules": {
+                        rule: [req.action.value, req.enforcement.value]
+                        for rule, req in sorted(layer.rules.items())
+                    },
+                }
+                for layer in ordered
+            ],
+            "exceptions": sorted(
+                [g.exception_id, g.rule_id, g.action.value, g.scope.value] for g in self.exceptions
+            ),
+            "mode": self.mode.value,
+        }
+        return json.dumps(document, separators=(",", ":"), sort_keys=True)
+
+    @property
+    def fingerprint(self) -> str:
+        return sha256_hex(self.canonical().encode("utf-8"))
+
+    def describe(self) -> str:
+        parts = [layer.label for layer in self.ordered_layers()]
+        if self.exceptions:
+            parts.append(f"{len(self.exceptions)} exception(s)")
+        if self.mode is RepositoryMode.MONITOR:
+            parts.append("monitor mode")
+        return " + ".join(parts) if parts else "no organization governance"
+
+    def ordered_layers(self) -> list[PolicyLayer]:
+        return sorted(self.layers, key=lambda layer: (_LEVEL_ORDER[layer.level], layer.label))
+
+
+class PolicyConflict(BaseModel):
+    """A lower layer asked for less than a mandatory requirement allows."""
+
+    model_config = _STRICT
+
+    policy_id: str
+    requested_action: Action
+    requested_enabled: bool
+    requested_by: PolicyLevel
+    requested_label: str
+    required_action: Action
+    required_by: PolicyLevel
+    required_label: str
+    effective_action: Action
+    reason: str
+
+
+class RuleProvenance(BaseModel):
+    """The effective policy for one rule and where every part of it came from."""
+
+    model_config = _STRICT
+
+    policy_id: str
+    enabled: bool
+    action: Action
+    source: PolicyLevel
+    source_label: str
+    enforcement: Enforcement | None = None
+    required_action: Action | None = None  # the floor, when a mandatory entry exists
+    required_by: PolicyLevel | None = None
+    required_label: str | None = None
+    conflict: PolicyConflict | None = None
+    exception_id: str | None = None
+    exception_expires_at: datetime | None = None
+    action_before_exception: Action | None = None
+    monitor_mode: bool = False  # block reported as warn
+    repository_configuration_known: bool = True
+
+
+class EffectivePolicy(BaseModel):
+    """The resolved policy set for one repository plus its provenance."""
+
+    model_config = _STRICT
+
+    policies: tuple[Policy, ...]
+    rules: tuple[RuleProvenance, ...]
+    inputs_fingerprint: str
+    description: str
+    mode: RepositoryMode
+
+    def policy_set(self) -> PolicySet:
+        return PolicySet({p.id: p for p in self.policies})
+
+    @property
+    def conflicts(self) -> tuple[PolicyConflict, ...]:
+        return tuple(r.conflict for r in self.rules if r.conflict is not None)
+
+    @property
+    def fingerprint(self) -> str:
+        """Fingerprint of the evaluated policies (same scheme as scan results)."""
+        return policy_set_fingerprint(self.policy_set())
+
+
+def policy_set_fingerprint(policies: Mapping[str, Policy]) -> str:
+    parts: list[str] = []
+    for policy in policies.values():
+        parts += [policy.id, str(policy.enabled), policy.action.value]
+    return fingerprint(parts)
+
+
+def _level_label(level: PolicyLevel) -> str:
+    return {
+        PolicyLevel.BUILT_IN: "Built-in default",
+        PolicyLevel.REPOSITORY_CONFIGURATION: "Repository configuration (.commitguard.yaml)",
+    }.get(level, level.value.replace("_", " ").capitalize())
+
+
+def _touched(configs: Sequence[CommitGuardConfig], policy_id: str) -> bool:
+    return any(
+        policy_id in config.policies and config.policies[policy_id].model_fields_set
+        for config in configs
+    )
+
+
+def _effective_rank(policy: Policy) -> int:
+    return policy.action.rank if policy.enabled else Action.ALLOW.rank
+
+
+def resolve_policy(
+    inputs: GovernanceInputs,
+    repository_configs: Sequence[CommitGuardConfig] | None = None,
+) -> EffectivePolicy:
+    """Resolve the effective policy for one repository.
+
+    ``repository_configs`` are the repository's configuration layers as loaded
+    from the trusted revision (the built-in empty layer may be included). Pass
+    ``None`` when they are not known (dashboard views between scans): the result
+    then shows what governance guarantees, and marks the repository layer unknown.
+    """
+    layers = inputs.ordered_layers()
+    known = repository_configs is not None
+    configs = list(repository_configs or ())
+
+    # Steps 2-4: defaults, narrower levels replacing broader ones.
+    defaults: dict[str, tuple[Action, PolicyLevel, str]] = {}
+    for level in (PolicyLevel.ORGANIZATION, PolicyLevel.GROUP, PolicyLevel.REPOSITORY_POLICY):
+        level_entries: dict[str, list[tuple[Action, str]]] = {}
+        for layer in (candidate for candidate in layers if candidate.level is level):
+            for rule, requirement in layer.rules.items():
+                if requirement.enforcement is Enforcement.DEFAULT:
+                    level_entries.setdefault(rule, []).append((requirement.action, layer.label))
+        for rule, entries in level_entries.items():
+            # Several groups: the most restrictive default wins (ties: first label).
+            action, label = max(entries, key=lambda entry: entry[0].rank)
+            defaults[rule] = (action, level, label)
+    defaults_config = CommitGuardConfig(
+        version=1,
+        policies={rule: PolicyOverride(action=entry[0]) for rule, entry in defaults.items()},
+    )
+
+    # Step 5: the repository configuration overrides defaults (policy engine layering).
+    requested = build_policy_set(defaults_config, *configs)
+
+    # Step 6: mandatory floors.
+    floors: dict[str, tuple[Action, PolicyLevel, str]] = {}
+    for layer in layers:
+        for rule, requirement in layer.rules.items():
+            if requirement.enforcement is not Enforcement.MANDATORY:
+                continue
+            current = floors.get(rule)
+            if current is None or requirement.action.rank > current[0].rank:
+                floors[rule] = (requirement.action, layer.level, layer.label)
+    floor_config = CommitGuardConfig(
+        version=1,
+        policies={rule: PolicyOverride(action=entry[0]) for rule, entry in floors.items()},
+    )
+    floored = apply_mandatory_policies(requested, floor_config) if floors else requested
+
+    grants: dict[str, list[ExceptionGrant]] = {}
+    for grant in inputs.exceptions:
+        grants.setdefault(grant.rule_id, []).append(grant)
+
+    policies: list[Policy] = []
+    provenance: list[RuleProvenance] = []
+    for policy_id in sorted(DEFAULT_POLICIES):
+        before_floor = requested[policy_id]
+        if _touched(configs, policy_id):
+            source, label, enforcement = (
+                PolicyLevel.REPOSITORY_CONFIGURATION,
+                _level_label(PolicyLevel.REPOSITORY_CONFIGURATION),
+                None,
+            )
+        elif policy_id in defaults:
+            _, source, label = defaults[policy_id]
+            enforcement = Enforcement.DEFAULT
+        else:
+            source, label, enforcement = (
+                PolicyLevel.BUILT_IN,
+                _level_label(PolicyLevel.BUILT_IN),
+                None,
+            )
+        policy = floored[policy_id]
+        conflict = None
+        floor = floors.get(policy_id)
+        if floor is not None:
+            floor_action, floor_level, floor_label = floor
+            if source is PolicyLevel.BUILT_IN:
+                # Nobody asked for less: the floor simply decides the rule.
+                if policy.action.rank == floor_action.rank:
+                    source, label, enforcement = floor_level, floor_label, Enforcement.MANDATORY
+            elif _effective_rank(before_floor) < floor_action.rank:
+                asked = before_floor.action if before_floor.enabled else Action.ALLOW
+                conflict = PolicyConflict(
+                    policy_id=policy_id,
+                    requested_action=asked,
+                    requested_enabled=before_floor.enabled,
+                    requested_by=source,
+                    requested_label=label,
+                    required_action=floor_action,
+                    required_by=floor_level,
+                    required_label=floor_label,
+                    effective_action=policy.action,
+                    reason=(
+                        f"{floor_label} requires at least {floor_action.value} and is mandatory: "
+                        f"{label} cannot weaken it."
+                    ),
+                )
+                source, label, enforcement = floor_level, floor_label, Enforcement.MANDATORY
+
+        exception_id = None
+        exception_expires = None
+        before_exception = None
+        applicable = grants.get(policy_id, [])
+        if applicable:
+            specificity = max(_SCOPE_SPECIFICITY[g.scope] for g in applicable)
+            narrowest = [g for g in applicable if _SCOPE_SPECIFICITY[g.scope] == specificity]
+            # The most restrictive of the most specific exceptions (safer on overlap).
+            grant = max(narrowest, key=lambda g: (g.action.rank, g.exception_id))
+            if _effective_rank(policy) > grant.action.rank:
+                before_exception = policy.action
+                policy = policy.model_copy(update={"enabled": True, "action": grant.action})
+                exception_id, exception_expires = grant.exception_id, grant.expires_at
+                source, label = PolicyLevel.EXCEPTION, f"Exception ({grant.scope_label})"
+
+        monitor = False
+        if (
+            inputs.mode is RepositoryMode.MONITOR
+            and policy.enabled
+            and policy.action is Action.BLOCK
+        ):
+            policy = policy.model_copy(update={"action": Action.WARN})
+            monitor = True
+
+        policies.append(policy)
+        provenance.append(
+            RuleProvenance(
+                policy_id=policy_id,
+                enabled=policy.enabled,
+                action=policy.action,
+                source=source,
+                source_label=label,
+                enforcement=enforcement,
+                required_action=floor[0] if floor else None,
+                required_by=floor[1] if floor else None,
+                required_label=floor[2] if floor else None,
+                conflict=conflict,
+                exception_id=exception_id,
+                exception_expires_at=exception_expires,
+                action_before_exception=before_exception,
+                monitor_mode=monitor,
+                repository_configuration_known=known,
+            )
+        )
+    return EffectivePolicy(
+        policies=tuple(policies),
+        rules=tuple(provenance),
+        inputs_fingerprint=inputs.fingerprint,
+        description=inputs.describe(),
+        mode=inputs.mode,
+    )
+
+
+def floor_config(inputs: GovernanceInputs) -> CommitGuardConfig | None:
+    """The combined mandatory floor of ``inputs`` (for display and compatibility)."""
+    floors: dict[str, Action] = {}
+    for layer in inputs.layers:
+        for rule, requirement in layer.rules.items():
+            if requirement.enforcement is Enforcement.MANDATORY:
+                floors[rule] = Action.most_restrictive(
+                    [requirement.action, floors.get(rule, Action.WARN)]
+                )
+    if not floors:
+        return None
+    return CommitGuardConfig(
+        version=1, policies={rule: PolicyOverride(action=action) for rule, action in floors.items()}
+    )

commitguard/policies/loader.py

@@ -0,0 +1,23 @@
+"""Build the effective :class:`PolicySet` from validated configuration layers.
+
+Merge semantics: start from :data:`DEFAULT_POLICIES`; each configuration layer
+(in precedence order, lowest first) overrides only the policy fields it sets.
+A policy that is *omitted* keeps its value from the layer below and,
+ultimately, its secure default - weakening enforcement always requires an
+explicit entry.
+"""
+
+from commitguard.config.schema import CommitGuardConfig
+from commitguard.policies.defaults import DEFAULT_POLICIES
+from commitguard.policies.model import Policy, PolicySet
+
+
+def build_policy_set(*configs: CommitGuardConfig) -> PolicySet:
+    """Return the effective policies for configuration layers ``configs``."""
+    effective: dict[str, Policy] = dict(DEFAULT_POLICIES)
+    for config in configs:
+        for policy_id, override in config.policies.items():
+            # Schema validation guarantees policy_id is a known ID.
+            updates = override.model_dump(exclude_unset=True)
+            effective[policy_id] = effective[policy_id].model_copy(update=updates)
+    return PolicySet(effective)

commitguard/policies/mandatory.py

@@ -0,0 +1,52 @@
+"""Mandatory policies: a floor that repository configuration cannot weaken.
+
+Ordinary configuration layers *override* each other (a repository may change
+``bot_identity`` from warn to allow). A mandatory policy - set by the operator
+of a central service such as the GitHub App, and in future by an organisation -
+is applied *after* those layers and can only make enforcement stricter:
+
+* a policy it names is always enabled;
+* its action is the more restrictive of the mandatory action and the action
+  the lower layers produced.
+
+So with a mandatory ``ai_coauthor: block``, a repository ``ai_coauthor: allow``
+(or ``enabled: false``) still results in BLOCK. A mandatory policy cannot
+disable or relax anything; ``enabled: false``, local hook enforcement and
+``remediation`` (which can turn a block into a commit) are rejected as
+configuration errors rather than silently ignored.
+"""
+
+from commitguard.config.schema import CommitGuardConfig
+from commitguard.core.decision import Action
+from commitguard.policies.defaults import DEFAULT_POLICIES
+from commitguard.policies.model import PolicySet
+
+
+def validate_mandatory_config(config: CommitGuardConfig) -> None:
+    """Raise ``ValueError`` if ``config`` tries to weaken rather than enforce."""
+    disabled = sorted(pid for pid, o in config.policies.items() if o.enabled is False)
+    if disabled:
+        raise ValueError(
+            "a mandatory policy can only enforce policies; enabled: false is not allowed for "
+            + ", ".join(disabled)
+        )
+    if config.enforcement.model_fields_set:
+        raise ValueError("a mandatory policy cannot configure local hook enforcement")
+    if config.remediation.model_fields_set:
+        # auto_remove turns a block into a commit. A floor may only make
+        # enforcement stricter, so it must never be able to switch that on.
+        raise ValueError("a mandatory policy cannot configure remediation")
+
+
+def apply_mandatory_policies(policies: PolicySet, mandatory: CommitGuardConfig) -> PolicySet:
+    """Return ``policies`` with the mandatory floor applied (never weaker)."""
+    validate_mandatory_config(mandatory)
+    effective = dict(policies)
+    for policy_id, override in mandatory.policies.items():
+        current = effective[policy_id]
+        floor = override.action or DEFAULT_POLICIES[policy_id].action
+        action = current.action if current.enabled else Action.ALLOW
+        effective[policy_id] = current.model_copy(
+            update={"enabled": True, "action": Action.most_restrictive([action, floor])}
+        )
+    return PolicySet(effective)