core-runtime 0.1.1__py3-none-any.whl

mind/governance/entry_point_policy.py

@@ -0,0 +1,62 @@
+# src/mind/governance/entry_point_policy.py
+
+"""
+Entry point allow-list policy for audit severity downgrading.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+
+
+# ID: 86699225-ae44-4a9a-926c-87bb365f5b7c
+class EntryPointAllowList:
+    """
+    Allow-list of entry_point_type values for which we downgrade dead-public-symbol findings.
+
+    These are architectural patterns that intentionally have public symbols
+    without direct internal callers (CLI commands, base classes, data models, etc).
+    """
+
+    def __init__(self, allowed_types: Iterable[str]) -> None:
+        self.allowed = {t.strip() for t in allowed_types if t and t.strip()}
+
+    @classmethod
+    # ID: a0594887-ebb4-429f-b2cf-976e266e2796
+    def default(cls) -> EntryPointAllowList:
+        """Standard allow-list based on CORE's architectural patterns."""
+        return cls(
+            allowed_types=[
+                # Structural/data constructs
+                "data_model",
+                "enum",
+                "magic_method",
+                "visitor_method",
+                "base_class",
+                "boilerplate_method",
+                # CLI & wrappers
+                "cli_command",
+                "cli_wrapper",
+                "registry_accessor",
+                # Orchestration/factories
+                "orchestrator",
+                "factory",
+                # Providers/adapters/clients
+                "provider_method",
+                "client_surface",
+                "client_adapter",
+                "io_handler",
+                "git_adapter",
+                "utility_function",
+                # Knowledge & governance pipelines
+                "knowledge_core",
+                "governance_check",
+                "auditor_pipeline",
+                # Capabilities
+                "capability",
+            ]
+        )
+
+    def __contains__(self, entry_point_type: str | None) -> bool:
+        """Check if an entry_point_type is in the allow-list."""
+        return bool(entry_point_type) and entry_point_type in self.allowed

mind/governance/executable_rule.py

@@ -0,0 +1,127 @@
+# src/mind/governance/executable_rule.py
+"""
+ExecutableRule - Represents a constitutional rule that can be executed via an engine.
+
+This dataclass bridges the gap between policy JSON declarations and runtime execution.
+It extracts the essential execution information from policy rules, allowing the audit
+system to execute rules directly from JSON without requiring Python Check classes.
+
+Design Philosophy:
+- Rules live in .intent/ policies (Mind layer)
+- Engines execute them (Body layer)
+- This dataclass is just the connector (pure data)
+
+Ref: Dynamic Rule Execution Architecture
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+# ID: ff4bed96-5d93-4e3f-84dc-5f980af199fb
+class ExecutableRule:
+    """
+    Represents a constitutional rule ready for execution.
+
+    Extracted from policy JSON with structure:
+    {
+        "id": "rule.name",
+        "enforcement": "error",
+        "authority": "policy",          # "constitution" | "policy"
+        "check": {
+            "engine": "ast_gate",
+            "params": {"check_type": "...", ...}
+        },
+        "scope": ["src/**/*.py"],
+        "exclusions": ["tests/**"]
+    }
+    """
+
+    rule_id: str
+    """Unique rule identifier (e.g., 'async.runtime.no_nested_loop_creation')"""
+
+    engine: str
+    """Engine identifier (e.g., 'ast_gate', 'llm_gate', 'knowledge_gate')"""
+
+    params: dict[str, Any]
+    """Engine-specific parameters (e.g., {'check_type': 'restrict_event_loop_creation'})"""
+
+    enforcement: str
+    """Severity level: 'error' or 'warning'"""
+
+    statement: str = ""
+    """Human-readable rule statement"""
+
+    scope: list[str] = field(default_factory=lambda: ["src/**/*.py"])
+    """File patterns to include (glob patterns)"""
+
+    exclusions: list[str] = field(default_factory=list)
+    """File patterns to exclude (glob patterns)"""
+
+    policy_id: str = ""
+    """Source policy identifier for traceability"""
+
+    is_context_level: bool = False
+    """
+    Whether this rule dispatches via ``engine.verify_context`` (whole
+    repository) or ``engine.verify(file_path)`` (one call per matching
+    file).
+
+    ADR-076: mode is owned by the engine *per check_type*, not by the
+    engine as a whole. ``rule_extractor`` consults
+    ``engine_cls.is_context_level_for(check_type)`` (a classmethod, no
+    instantiation) and stores the result here. Mixed-mode engines —
+    notably ``artifact_gate`` — return True for some check_types and
+    False for others. Engines that do not override the classmethod
+    inherit ``False`` from BaseEngine.
+    """
+
+    authority: str = "policy"
+    """
+    Who declared this rule and how binding it is.
+
+    - "constitution": Declared by the sovereign constitution. Always blocks,
+      regardless of strict_mode. These rules cannot be made advisory.
+    - "policy":       Declared by an operational policy. Advisory by default;
+      blocks only when IntentGuard is initialised with strict_mode=True.
+
+    Sourced directly from the rule's 'authority' field in the .intent/ document.
+    Defaults to "policy" (the safer, less disruptive tier) when absent.
+    """
+
+    requires_findings_from: list[str] = field(default_factory=list)
+    """
+    Pre-selector dependency list (ADR-043 D2).
+
+    When non-empty, the rule's per-file scope is intersected at execution
+    time with the set of files that have findings under any of the listed
+    rule IDs in the current audit run. Empty list means no pre-selection
+    (run against full scope as today).
+
+    Populated by rule_extractor from the enforcement mapping YAML. The
+    audit driver runs rules in topological order over these edges so
+    prior findings are available when a dependent rule executes.
+    Validation (referenced IDs exist, no cycles, not combined with
+    is_context_level=True) happens at extraction time.
+    """
+
+    rule_content_hash: str = ""
+    """
+    SHA-256 of the canonicalised (rule + enforcement strategy) dict — the
+    cache key for ADR-044's llm_gate verdict cache. Combines the rule's
+    canonical fields with its enforcement mapping so any meaningful
+    governance change (prompt text edit, threshold change, scope
+    narrowing) invalidates the affected cached verdicts.
+
+    Computed by rule_extractor at audit-context load time via
+    shared.infrastructure.intent.intent_repository.compute_rule_content_hash.
+    Empty default means "cache disabled" — the llm_gate engine treats a
+    blank hash as a signal to bypass DB cache and always call the LLM.
+    """
+
+    def __repr__(self) -> str:
+        """Concise representation for logging."""
+        return f"ExecutableRule({self.rule_id}, engine={self.engine}, authority={self.authority})"

mind/governance/filtered_audit.py

@@ -0,0 +1,272 @@
+# src/mind/governance/filtered_audit.py
+"""
+Filtered Constitutional Audit - Run specific rules or policies.
+
+Enables focused remediation by allowing execution of:
+- Single rules: --rule linkage.capability.unassigned
+- Single policies: --policy standard_code_linkage
+- Multiple rules: --rule rule1 --rule rule2
+- Rule patterns: --rule-pattern "linkage.*"
+
+This uses the existing dynamic rule execution engine but with filtering.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import re
+from typing import TYPE_CHECKING
+
+from shared.logger import getLogger
+
+
+if TYPE_CHECKING:
+    from mind.governance.audit_context import AuditorContext
+    from mind.governance.executable_rule import ExecutableRule
+    from shared.models import AuditFinding
+
+logger = getLogger(__name__)
+
+
+# ID: f8a9b7c6-5d4e-3f2a-1b0c-9d8e7f6a5b4c
+class RuleFilter:
+    """Filters rules based on user-specified criteria."""
+
+    def __init__(
+        self,
+        rule_ids: list[str] | None = None,
+        policy_ids: list[str] | None = None,
+        rule_patterns: list[str] | None = None,
+    ):
+        self.rule_ids = set(rule_ids or [])
+        self.policy_ids = set(policy_ids or [])
+        self.rule_patterns = [re.compile(p) for p in (rule_patterns or [])]
+
+    # ID: ee2ebac1-0f32-45ce-ab11-ed0c4106ab20
+    def matches(self, rule: ExecutableRule) -> bool:
+        """Check if rule matches filter criteria."""
+        # If no filters specified, match everything
+        if not self.rule_ids and not self.policy_ids and not self.rule_patterns:
+            return True
+
+        # Check exact rule ID match
+        if self.rule_ids and rule.rule_id in self.rule_ids:
+            return True
+
+        # Check policy ID match
+        if self.policy_ids and rule.policy_id in self.policy_ids:
+            return True
+
+        # Check pattern match
+        for pattern in self.rule_patterns:
+            if pattern.match(rule.rule_id):
+                return True
+
+        return False
+
+
+# ID: 5872afdb-b32c-48d0-b280-e2403aca3b64
+def normalize_file_filter(
+    files: list[str] | None,
+    repo_path,  # Path-like; quoted to avoid an Iterable hop.
+) -> frozenset[str] | None:
+    """
+    Normalize a CLI --files list to a frozenset of repo-relative POSIX
+    paths suitable for execute_rule's file_filter parameter.
+
+    Accepts repo-relative ('src/foo.py'), './'-prefixed
+    ('./src/foo.py'), and absolute paths. Paths outside the repo are
+    rejected loudly — silently dropping them would mask user error and
+    produce a confusing empty audit.
+
+    Returns None when the input is empty/None — the audit runs without
+    a file filter (full scope).
+    """
+    from pathlib import Path
+
+    if not files:
+        return None
+
+    repo_root = Path(repo_path).resolve()
+    normalized: set[str] = set()
+    for raw in files:
+        # Always resolve before validating. pathlib's `/` operator drops
+        # the LHS when the RHS is absolute, so a single expression handles
+        # both repo-relative and absolute inputs. Resolving first
+        # normalizes `..` segments and follows symlinks, so the
+        # `relative_to(repo_root)` check below is a real boundary, not a
+        # lexical one — `/<repo>/x/../../etc/passwd` and `/<repo>/symlink`
+        # pointing outside both reject. Closes CodeQL py/path-injection.
+        absolute = (repo_root / Path(raw)).resolve()
+        try:
+            rel = absolute.relative_to(repo_root)
+        except ValueError as exc:
+            raise ValueError(
+                f"--files path {raw!r} is outside the repository root "
+                f"{repo_root}: {exc}"
+            ) from exc
+        normalized.add(str(rel).replace("\\", "/"))
+
+    return frozenset(normalized)
+
+
+# ID: d5383238-b6d4-48d9-880b-8f48df47d57e
+async def run_filtered_audit(
+    context: AuditorContext,
+    *,
+    rule_ids: list[str] | None = None,
+    policy_ids: list[str] | None = None,
+    rule_patterns: list[str] | None = None,
+    executed_rule_ids: set[str] | None = None,
+    files: list[str] | None = None,
+) -> tuple[list, set[str], dict[str, int]]:
+    """
+    Execute filtered subset of constitutional rules.
+
+    Args:
+        context: AuditorContext with repo and policy info
+        rule_ids: Specific rule IDs to execute
+        policy_ids: Execute all rules from these policies
+        rule_patterns: Regex patterns for rule IDs
+        executed_rule_ids: Set to track executed rules (optional)
+        files: Optional list of file paths (repo-relative, ./-prefixed,
+            or absolute) scoping per-file rules. Context-level rules
+            skip gracefully when this is set — they cannot be
+            meaningfully scoped to a file list. Closes #279.
+
+    Returns:
+        tuple(findings, executed_rules, stats)
+    """
+    from mind.governance.rule_executor import execute_rule
+    from mind.governance.rule_extractor import extract_executable_rules
+
+    if executed_rule_ids is None:
+        executed_rule_ids = set()
+
+    # ADR-039: rebuild the filesystem scan once per audit run so files
+    # committed since the last cycle are visible to every rule.
+    context.reload_governance()
+    context.invalidate_file_cache()
+
+    # ADR-044: TTL sweep at audit start. Idempotent per AuditorContext.
+    await context.sweep_llm_gate_cache()
+
+    file_filter = normalize_file_filter(files, context.repo_path)
+
+    # Extract all executable rules from policies
+    all_rules = extract_executable_rules(context.policies, context.enforcement_loader)
+
+    # Create filter
+    rule_filter = RuleFilter(
+        rule_ids=rule_ids,
+        policy_ids=policy_ids,
+        rule_patterns=rule_patterns,
+    )
+
+    # Filter rules
+    filtered_rules = [r for r in all_rules if rule_filter.matches(r)]
+
+    if not filtered_rules:
+        logger.warning(
+            "No rules matched filter criteria: rule_ids=%s, policy_ids=%s, patterns=%s",
+            rule_ids,
+            policy_ids,
+            rule_patterns,
+        )
+        return (
+            [],
+            executed_rule_ids,
+            {
+                "total_rules": len(all_rules),
+                "filtered_rules": 0,
+                "executed_rules": 0,
+                "total_findings": 0,
+                "skipped_context_level": 0,
+            },
+        )
+
+    logger.info(
+        "Filtered audit: %d rules selected (out of %d total)%s",
+        len(filtered_rules),
+        len(all_rules),
+        (
+            f" — file filter active ({len(file_filter)} file(s))"
+            if file_filter is not None
+            else ""
+        ),
+    )
+
+    # Execute filtered rules. ADR-043 D3: accumulator carries
+    # AuditFinding objects through the loop so requires_findings_from
+    # narrowing can read check_id and file_path off them; conversion to
+    # dicts is deferred to the return statement so the external contract
+    # is unchanged. Rules are topologically sorted by
+    # extract_executable_rules.
+    all_findings: list[AuditFinding] = []
+    failed_rules = []
+    skipped_context_level: list[str] = []
+
+    for rule in filtered_rules:
+        # ADR-081 Step 2b — cooperative yield at the per-rule boundary so
+        # heavy audit cycles can reach a cancellation point between rules.
+        # execute_rule itself is sync-dominated (AST walks per file); this
+        # yield bounds the worst case to one rule's worth of synchronous
+        # work between SIGTERM and Worker.start()'s `finally` block running.
+        # Per-engine inner yields are deferred pending Step 0 evidence
+        # naming which engines dominate the loop-hold.
+        await asyncio.sleep(0)
+
+        # Track skipped-context-level explicitly for stats / operator
+        # transparency. execute_rule logs the skip; we count it here.
+        if file_filter is not None and rule.is_context_level:
+            skipped_context_level.append(rule.rule_id)
+
+        try:
+            findings = await execute_rule(
+                rule,
+                context,
+                file_filter=file_filter,
+                prior_findings=all_findings,
+            )
+            all_findings.extend(findings)
+            executed_rule_ids.add(rule.rule_id)
+
+            logger.debug(
+                "Rule %s: %d findings",
+                rule.rule_id,
+                len(findings),
+            )
+        except Exception as e:
+            logger.error(
+                "Rule %s execution failed: %s",
+                rule.rule_id,
+                e,
+                exc_info=True,
+            )
+            failed_rules.append(rule.rule_id)
+
+    stats = {
+        "total_rules": len(all_rules),
+        "filtered_rules": len(filtered_rules),
+        "executed_rules": len(executed_rule_ids),
+        "failed_rules": len(failed_rules),
+        "total_findings": len(all_findings),
+        "skipped_context_level": len(skipped_context_level),
+    }
+
+    logger.info(
+        "Filtered audit complete: %d/%d rules executed, %d findings%s",
+        stats["executed_rules"],
+        stats["filtered_rules"],
+        stats["total_findings"],
+        (
+            f", {len(skipped_context_level)} context-level rule(s) skipped under --files"
+            if skipped_context_level
+            else ""
+        ),
+    )
+
+    if failed_rules:
+        logger.warning("Failed rules: %s", ", ".join(failed_rules))
+
+    return [f.as_dict() for f in all_findings], executed_rule_ids, stats

mind/governance/finding_processor.py

@@ -0,0 +1,76 @@
+# src/mind/governance/finding_processor.py
+
+"""
+Core logic for processing and downgrading audit findings.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable, Mapping, MutableMapping, Sequence
+
+from mind.governance.entry_point_policy import EntryPointAllowList
+
+
+# ID: f2778ec7-aa0d-4025-90c1-9af82c1f27fb
+def safe_symbol_meta(
+    symbol_index: Mapping[str, Mapping[str, object]], symbol_key: str
+) -> Mapping[str, object]:
+    """Safely retrieve symbol metadata from index."""
+    return symbol_index.get(symbol_key, {}) or {}
+
+
+# ID: 9875bf96-ccab-4a2a-bcd0-374da32f634e
+def process_findings_with_downgrade(
+    findings: Sequence[MutableMapping[str, object]],
+    symbol_index: Mapping[str, Mapping[str, object]],
+    allow_list: EntryPointAllowList,
+    dead_rule_ids: Iterable[str],
+    downgrade_to: str = "info",
+) -> tuple[list[MutableMapping[str, object]], list[dict[str, object]]]:
+    """
+    Process findings and downgrade severity for allowed entry points.
+
+    Args:
+        findings: List of audit findings to process
+        symbol_index: Mapping of symbol keys to their metadata
+        allow_list: Entry point types that should be downgraded
+        dead_rule_ids: Rule IDs that identify dead-public-symbol findings
+        downgrade_to: Target severity level for downgrade
+
+    Returns:
+        Tuple of (processed_findings, auto_ignored_items)
+    """
+    dead_ids = {r.strip() for r in dead_rule_ids if r and r.strip()}
+    processed: list[MutableMapping[str, object]] = []
+    auto_ignored: list[dict[str, object]] = []
+
+    for finding in findings:
+        rule_id = str(finding.get("rule_id", "") or "")
+        symbol_key = str(finding.get("symbol_key", "") or "")
+        severity = str(finding.get("severity", "") or "").lower()
+
+        if rule_id in dead_ids and symbol_key:
+            meta = safe_symbol_meta(symbol_index, symbol_key)
+            ep_type = str(meta.get("entry_point_type", "") or "")
+            pattern_name = str(meta.get("pattern_name", "") or "")
+            justification = str(meta.get("entry_point_justification", "") or "")
+
+            if ep_type in allow_list:
+                # Downgrade severity only if current is higher
+                if severity in {"error", "warn"}:
+                    finding["severity"] = downgrade_to
+
+                auto_ignored.append(
+                    {
+                        "symbol_key": symbol_key,
+                        "entry_point_type": ep_type,
+                        "pattern_name": pattern_name or None,
+                        "justification": justification or None,
+                        "original_rule_id": rule_id,
+                        "downgraded_to": finding.get("severity"),
+                    }
+                )
+
+        processed.append(finding)
+
+    return processed, auto_ignored