core-runtime 0.1.1__py3-none-any.whl

mind/coherence/checks/vocabulary.py

@@ -0,0 +1,112 @@
+# src/mind/coherence/checks/vocabulary.py
+"""VOCABULARY — surface non-canonical alias usage in governance artifacts.
+
+Per ADR-073 D8 / topology §6.2 vocabulary invariant.
+
+Mechanism (v1):
+  1. Load the canonical vocabulary projection at .intent/META/vocabulary.json.
+  2. For each (canonical_term, alias) pair in the projection, scan governance
+     artifacts (.specs/{decisions,papers,northstar}/*.md) for alias usage.
+  3. Emit a candidate when an alias appears in an artifact but the canonical
+     term does NOT also appear there — indicating non-canonical usage rather
+     than mere co-mention.
+
+False positives ride the standard CCC triage flow per D8.
+
+No LLM, no embeddings.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from pathlib import Path
+
+from .base import CoherenceCandidate
+
+
+# ID: a80cdd43-f35e-4af0-b034-67f1e0b46753
+class VocabularyCheck:
+    """Emit VOCABULARY for governance artifacts using non-canonical aliases."""
+
+    relation = "VOCABULARY"
+
+    # ID: 72eb54d5-6cfe-4f8b-9fd7-8bea4580452a
+    def __init__(self, repo_root: Path) -> None:
+        self._repo_root = Path(repo_root)
+
+    # ID: 3c0a85ca-154f-43ac-bc25-9fc458ced200
+    async def run(self) -> list[CoherenceCandidate]:
+        vocab_path = self._repo_root / ".intent" / "META" / "vocabulary.json"
+        if not vocab_path.exists():
+            return []
+        data = json.loads(vocab_path.read_text(encoding="utf-8"))
+        alias_map = _expand_alias_map(data.get("terms", []))
+        if not alias_map:
+            return []
+
+        artifacts = list(_iter_governance_markdown(self._repo_root))
+        candidates: list[CoherenceCandidate] = []
+        for path in artifacts:
+            content = path.read_text(encoding="utf-8", errors="replace")
+            rel = str(path.relative_to(self._repo_root))
+            for alias, canonical in alias_map.items():
+                if _whole_word(content, alias) and not _whole_word(content, canonical):
+                    candidates.append(
+                        CoherenceCandidate(
+                            relation=self.relation,
+                            documents=[rel],
+                            claim=(
+                                f"`{alias}` is used in {rel} but the canonical term "
+                                f"`{canonical}` does not appear in the same artifact."
+                            ),
+                            rationale=(
+                                "Topology §6.2 (vocabulary invariant) requires "
+                                "consistent term usage across the governance graph. "
+                                f"`{alias}` is registered as an alias of `{canonical}` "
+                                "in `.intent/META/vocabulary.json`. Using the alias "
+                                "without also mentioning the canonical term signals "
+                                "non-canonical usage rather than legitimate cross-reference. "
+                                "Replace the alias with the canonical term, or — if the "
+                                "alias is intended in a different sense — disambiguate "
+                                "explicitly. Governor triage may dismiss if context "
+                                "makes the alternative sense unambiguous."
+                            ),
+                        )
+                    )
+        return candidates
+
+
+# ID: 3aaf2f0a-616d-4247-a4f8-51fa3ee53204
+def _expand_alias_map(terms: list[dict]) -> dict[str, str]:
+    """Expand the alias projection into {alias_token: canonical_term}.
+
+    The vocabulary store stores some aliases as pipe-separated strings inside
+    a single list entry (`["Handler | Processor | Step"]`); this helper
+    splits them. Empty aliases produce no entries.
+    """
+    result: dict[str, str] = {}
+    for term in terms:
+        canonical = term.get("term")
+        if not canonical:
+            continue
+        for raw in term.get("aliases", []) or []:
+            if not isinstance(raw, str):
+                continue
+            for piece in raw.split("|"):
+                token = piece.strip()
+                if token and token.lower() != canonical.lower():
+                    result[token] = canonical
+    return result
+
+
+def _whole_word(content: str, token: str) -> bool:
+    """True iff `token` appears as a whole word in `content` (case-sensitive)."""
+    return re.search(rf"\b{re.escape(token)}\b", content) is not None
+
+
+def _iter_governance_markdown(repo_root: Path):
+    for sub in ("decisions", "papers", "northstar"):
+        directory = repo_root / ".specs" / sub
+        if directory.is_dir():
+            yield from sorted(directory.glob("*.md"))

mind/coherence/llm_judge.py

@@ -0,0 +1,207 @@
+# src/mind/coherence/llm_judge.py
+"""Shared LLM-judge logic for SAMECONCERN / R1_SCOPED contradiction verdicts.
+
+Per ADR-073 D5 tiered cosine policy:
+  - high_confidence tier: direct contradiction verdict prompt
+  - ambiguous tier: prompt variant asking explicitly about adjacency-vs-contradiction
+
+Preserves ADR-067 D3 prompt contract (constitutional_coherence_analyst role).
+"""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Any
+
+from shared.ai.response_parser import extract_json_safe
+from shared.logger import getLogger
+
+from .checks.base import CoherenceCandidate
+
+
+logger = getLogger(__name__)
+
+
+_LLM_CALL_TIMEOUT = 120
+_USER_ID = "coherence_checker"
+
+# Markers indicating the LLM emitted a candidate while admitting no contradiction
+# exists. The prompt asks for an empty array in that case; the model sometimes
+# returns a populated array whose rationale concedes alignment. Drop those.
+_NO_CONTRADICTION_MARKERS = (
+    "no contradiction",
+    "fully aligned",
+    "not contradictory",
+    "no candidate is warranted",
+    "no candidate is needed",
+    "no direct conflict",
+    "semantically equivalent",
+)
+
+
+_HIGH_CONFIDENCE_DESC = (
+    "Same-concern contradiction check. The two normative claims below were "
+    "flagged by vector similarity as addressing the same governance concern. "
+    "Determine whether they make conflicting claims about that concern. "
+    "Emit a candidate object only if the contradiction is real; otherwise "
+    "return an empty array."
+)
+
+_AMBIGUOUS_DESC = (
+    "Same-concern contradiction check (AMBIGUOUS TIER). The two normative "
+    "claims below were flagged by vector similarity as POTENTIALLY related "
+    "but the signal is in the ambiguous band. Distinguish carefully between:\n"
+    "  (a) genuine contradiction — they make incompatible claims about the same concern\n"
+    "  (b) topical adjacency — they discuss related topics without contradicting\n"
+    "Only (a) warrants a candidate. Return an empty array for (b)."
+)
+
+# Applied to every judge invocation regardless of tier. Authors who write
+# "Compatibility with X", "Relates to X", "Supersedes X", or "References X"
+# sections are signaling deliberate reconciliation; the judge must respect
+# that signal before asserting contradiction. See #474.
+_COMPATIBILITY_GUARDRAIL = (
+    "\n\n"
+    "Before asserting a contradiction, scan each document for sections that "
+    "explicitly address the other document — labels like 'Compatibility with X', "
+    "'Relates to X', 'Supersedes X', 'References X', or any prose where the "
+    "author reconciles the two. If either document declares the relationship "
+    "(e.g., 'this ADR is compatible with X because Y'), default to no candidate "
+    "unless the actual runtime behavior contradicts the declared compatibility. "
+    "Authors are trusted to know their own intent; the judge catches unintended "
+    "contradictions, not declared compatibility."
+)
+
+# Document headers carry an artifact-type label in parentheses (e.g.
+# "DOC A (Intent · worker mandate) — ..."). The LLM has historically
+# described worker YAMLs as "ADRs" in its rationale because every prior
+# prompt example anchored on ADR pairs. This guardrail forces the model
+# to honour the given label. See #475.
+_ARTIFACT_TYPE_GUARDRAIL = (
+    "\n\n"
+    "Each document header carries an artifact-type label in parentheses "
+    "(e.g., 'DOC A (ADR) — ...', 'DOC B (Intent · worker mandate) — ...'). "
+    "When you write the claim or rationale, refer to each document by the "
+    "label given. Do not call an Intent file an 'ADR'; do not call a Paper "
+    "an 'ADR'; do not generalise both documents as 'these ADRs' unless both "
+    "labels are 'ADR'. The labels are authoritative — your prose must match."
+)
+
+
+_CATEGORY_LABEL: dict[str, str] = {
+    "adr": "ADR",
+    "paper": "Paper",
+    "northstar": "Northstar",
+    "intent": "Intent file",
+}
+
+_INTENT_SUBCATEGORY: dict[str, str] = {
+    "workers": "Intent · worker mandate",
+    "policies": "Intent · policy",
+    "rules": "Intent · rule",
+    "enforcement": "Intent · enforcement config",
+    "workflows": "Intent · workflow",
+    "phases": "Intent · phase",
+    "taxonomies": "Intent · taxonomy",
+}
+
+
+def _artifact_label(category: str, source_path: str) -> str:
+    """Return a human-anchoring label for the (category, source_path) pair.
+
+    Non-intent categories return their plain label. Intent files are refined
+    by the first path segment under `.intent/` so the LLM sees, e.g.,
+    'Intent · worker mandate' rather than the generic 'Intent file'. Unknown
+    categories fall back to a lowercased label so the prompt still has *some*
+    anchor instead of an empty parenthetical.
+    """
+    if category == "intent":
+        parts = source_path.split("/")
+        if len(parts) >= 2 and parts[0] == ".intent":
+            subdir = parts[1]
+            return _INTENT_SUBCATEGORY.get(subdir, "Intent file")
+        return "Intent file"
+    return _CATEGORY_LABEL.get(category, category or "Document")
+
+
+# ID: 9ccc8a46-d93a-4d2b-89f0-8511915a4e46
+async def judge_contradiction_pair(
+    cognitive_service: Any,
+    text_a: str,
+    source_a: str,
+    text_b: str,
+    source_b: str,
+    tier: str,
+    relation: str = "SAMECONCERN",
+    category_a: str = "",
+    category_b: str = "",
+) -> CoherenceCandidate | None:
+    """Invoke the LLM to judge a pair of claims as contradiction or not.
+
+    Returns a CoherenceCandidate carrying the LLM's claim+rationale if a
+    contradiction is confirmed; None otherwise. All failure modes (timeout,
+    parse error, schema mismatch) yield None and are logged.
+    """
+    from shared.ai.prompt_model import PromptModel
+
+    base = _AMBIGUOUS_DESC if tier == "ambiguous" else _HIGH_CONFIDENCE_DESC
+    description = base + _COMPATIBILITY_GUARDRAIL + _ARTIFACT_TYPE_GUARDRAIL
+    label_a = _artifact_label(category_a, source_a)
+    label_b = _artifact_label(category_b, source_b)
+    documents_text = (
+        f"=== DOC A ({label_a}) — {source_a} ===\n{text_a}\n\n"
+        f"=== DOC B ({label_b}) — {source_b} ===\n{text_b}\n\n"
+    )
+
+    try:
+        model = PromptModel.load("constitutional_coherence_analyst")
+        client = await cognitive_service.aget_client_for_role(model.manifest.role)
+        raw = await asyncio.wait_for(
+            model.invoke(
+                context={
+                    "relation_description": description,
+                    "documents_text": documents_text,
+                },
+                client=client,
+                user_id=_USER_ID,
+            ),
+            timeout=_LLM_CALL_TIMEOUT,
+        )
+    except TimeoutError:
+        logger.warning("LLM judge: timed out after %ds", _LLM_CALL_TIMEOUT)
+        return None
+    except Exception as exc:
+        logger.warning("LLM judge: call failed: %s", exc)
+        return None
+
+    parsed = extract_json_safe(raw)
+    if isinstance(parsed, dict):
+        unwrapped = next((v for v in parsed.values() if isinstance(v, list)), None)
+        if unwrapped is not None:
+            parsed = unwrapped
+    if not isinstance(parsed, list) or not parsed:
+        return None
+
+    first = parsed[0]
+    if not isinstance(first, dict):
+        return None
+    claim = first.get("claim")
+    rationale = first.get("rationale")
+    if not isinstance(claim, str) or not isinstance(rationale, str):
+        return None
+
+    text = (claim + " " + rationale).lower()
+    if any(marker in text for marker in _NO_CONTRADICTION_MARKERS):
+        logger.debug(
+            "LLM judge: dropped aligned-noise candidate (%s ↔ %s)",
+            source_a,
+            source_b,
+        )
+        return None
+
+    return CoherenceCandidate(
+        relation=relation,
+        documents=[source_a, source_b],
+        claim=claim,
+        rationale=rationale,
+    )

mind/enforcement/audit.py

@@ -0,0 +1,78 @@
+# src/mind/enforcement/audit.py
+
+"""
+Provides functionality for the audit module.
+
+Refactored to be stateless and pure async (logic layer).
+Now HEADLESS: Returns data, does not logger.info(LOG-001 compliance).
+
+CONSTITUTIONAL FIX:
+- Integrated with shared.infrastructure.validation.test_runner for Traceable Evidence.
+- Promoted test_system to async-native.
+"""
+
+from __future__ import annotations
+
+from shared.logger import getLogger
+
+
+logger = getLogger(__name__)
+
+from mind.governance.auditor import ConstitutionalAuditor
+from shared.action_types import ActionImpact, ActionResult
+from shared.atomic_action import atomic_action
+from shared.context import CoreContext
+from shared.models import AuditFinding
+from shared.utils.subprocess_utils import run_poetry_command
+
+
+# ID: 7de7e5c2-0fbf-4028-8111-e3722b7d0ad9
+async def run_audit_workflow(context: CoreContext) -> tuple[bool, list[AuditFinding]]:
+    """
+    The core async logic for running the audit.
+
+    Returns:
+        tuple(passed: bool, findings: list[AuditFinding])
+    """
+    # Inject Qdrant service from CoreContext into AuditorContext
+    auditor_context = context.auditor_context
+    if context.qdrant_service and not hasattr(auditor_context, "qdrant_service"):
+        auditor_context.qdrant_service = context.qdrant_service
+
+    auditor = ConstitutionalAuditor(auditor_context)
+    results = await auditor.run_full_audit_async()
+    return results["passed"], results["findings"]
+
+
+# ID: 09884f64-313e-4f9d-84d0-de9e2d16a8d3
+def lint() -> None:
+    """Checks code formatting and quality using Black and Ruff."""
+    run_poetry_command(
+        "🔎 Checking code format with Black...", ["black", "--check", "src", "tests"]
+    )
+    run_poetry_command(
+        "🔎 Checking code quality with Ruff...", ["ruff", "check", "src", "tests"]
+    )
+
+
+@atomic_action(
+    action_id="test.system",
+    intent="Atomic action for test_system",
+    impact=ActionImpact.WRITE_CODE,
+    policies=["atomic_actions"],
+)
+# ID: 5963ab12-7398-4506-a257-0836ec585a88
+async def test_system(core_context: CoreContext, **kwargs) -> ActionResult:
+    """
+    Run the project test suite via the canonical async test runner.
+
+    This bridge ensures that test results are:
+    1. Recorded in core.action_results (Database SSOT)
+    2. Available as structured JSON evidence in var/reports/
+    3. Interpretable by CORE agents and governance engines.
+
+    Dispatches through ActionExecutor so the inner ``test.execute`` action
+    runs with ``_executor_token == "test.execute"`` (ADR-079 identity
+    propagation) rather than the enclosing ``test.system`` token.
+    """
+    return await core_context.action_executor.execute("test.execute")

mind/governance/__init__.py

@@ -0,0 +1,22 @@
+# src/mind/governance/__init__.py
+"""
+Mind Layer Governance Module
+
+CONSTITUTIONAL ARCHITECTURE:
+Mind layer contains pure query interfaces and data structures.
+Execution logic has been moved to Body layer.
+
+COMPATIBILITY NOTE:
+Execution components (IntentGuard, EngineDispatcher, PatternValidators)
+have moved to body.governance. Update imports:
+
+OLD: from body.governance.intent_guard import IntentGuard
+NEW: from body.governance.intent_guard import IntentGuard
+
+Data structures (ViolationReport, PolicyRule) remain in Mind.
+"""
+
+from __future__ import annotations
+
+# NO re-exports to avoid circular imports
+# Import directly from the actual module locations