core-runtime 0.1.1__py3-none-any.whl

mind/coherence/checks/row3_citation.py

@@ -0,0 +1,119 @@
+# src/mind/coherence/checks/row3_citation.py
+"""ROW3_CITATION — every normative paper § cites an enforcing rule or marks
+itself aspirational.
+
+Per ADR-073 D6 / topology §10.2 row 3. Operationalizes ADR-049 D2's existing
+constitutional obligation that has been declared-but-unenforced.
+
+Mechanism: split each paper into top-level §s, classify each via the §2.5
+marker register from D10, emit when a normative section has no rule citation
+and no aspirational/pending/deferred marker.
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+from shared.governance.coherence_harvester import NormativeMarkerRegister
+
+from .base import CoherenceCandidate
+
+
+_HEADING = re.compile(r"^(#{1,3})\s+(.+?)\s*$", re.MULTILINE)
+_RULE_CITE = re.compile(r"\.intent/[\w\-.]+/[\w\-./*{}]+\.[a-z]+", re.IGNORECASE)
+_LEADING_NUMBERING = re.compile(r"^[\d.]+\s*")
+
+# Headings that legitimately use normative vocabulary about the paper's own
+# process (amendment mechanism, status lifecycle) rather than about runtime
+# behavior. ADR-049 D2's citation obligation does not apply — there is no
+# operational rule to cite. Definition sections are deliberately NOT in this
+# set; they carry rule-enforceable claims about the paper's subject.
+_BOILERPLATE_HEADINGS = frozenset(
+    {
+        "purpose",
+        "abstract",
+        "motivation",
+        "problem statement",
+        "the problem",
+        "alignment statement",
+        "conclusion",
+        "closing statement",
+        "summary",
+        "non-goals",
+        "relationship to other papers",
+        "amendment discipline",
+        "status: superseded",
+        "why it was superseded",
+        "constitutional identity",
+        "constitutional identity (historical)",
+    }
+)
+
+
+# ID: b70fb5d2-9de3-4575-b1b2-58f4c88cc147
+class Row3CitationCheck:
+    """Emit ROW3_CITATION for normative paper §s missing rule citation or aspirational marker."""
+
+    relation = "ROW3_CITATION"
+
+    # ID: 2cf281c7-a32b-4b91-ab6e-abe4ad406427
+    def __init__(self, repo_root: Path, register: NormativeMarkerRegister) -> None:
+        self._repo_root = Path(repo_root)
+        self._register = register
+        self._aspirational = re.compile(
+            "|".join(re.escape(m) for m in register.aspirational_markers),
+            re.IGNORECASE,
+        )
+
+    # ID: 8cbccb3a-6a50-4d88-82d6-e6b231434064
+    async def run(self) -> list[CoherenceCandidate]:
+        papers = self._repo_root / ".specs" / "papers"
+        if not papers.is_dir():
+            return []
+        candidates: list[CoherenceCandidate] = []
+        for path in sorted(papers.glob("*.md")):
+            content = path.read_text(encoding="utf-8", errors="replace")
+            rel = str(path.relative_to(self._repo_root))
+            for heading, section_text in _iter_sections(content):
+                normalized = _LEADING_NUMBERING.sub("", heading).strip().lower()
+                if normalized in _BOILERPLATE_HEADINGS:
+                    continue
+                if not self._register.marker_pattern.search(section_text):
+                    continue
+                if _RULE_CITE.search(section_text):
+                    continue
+                if self._register.aspirational_markers and self._aspirational.search(
+                    section_text
+                ):
+                    continue
+                candidates.append(
+                    CoherenceCandidate(
+                        relation=self.relation,
+                        documents=[rel],
+                        claim=(
+                            f"Paper § '{heading}' contains normative markers but "
+                            "cites no enforcing rule and carries no aspirational/pending marker."
+                        ),
+                        rationale=(
+                            "ADR-049 D2 (operationalized by topology row 3) requires "
+                            "every normative paper § to either name a `.intent/rules/...` "
+                            "artifact that enforces the claim, or explicitly mark "
+                            "itself aspirational/pending/deferred. Neither was detected in "
+                            "this section. Either backfill the rule citation or add "
+                            "an aspirational marker so the claim's status is honest."
+                        ),
+                    )
+                )
+        return candidates
+
+
+def _iter_sections(content: str):
+    """Yield (heading_text, section_body) for each top-level heading."""
+    matches = list(_HEADING.finditer(content))
+    if not matches:
+        return
+    for i, m in enumerate(matches):
+        start = m.end()
+        end = matches[i + 1].start() if i + 1 < len(matches) else len(content)
+        yield m.group(2).strip(), content[start:end]

mind/coherence/checks/row4_naming.py

@@ -0,0 +1,126 @@
+# src/mind/coherence/checks/row4_naming.py
+"""ROW4_NAMING — every `.intent/` artifact is named in at least one accepted
+ADR's D-text, or predates topology paper acceptance (grandfathered).
+
+Per ADR-073 D6 / topology §10.2 row 4 + §11.1 backfill-on-touch posture.
+
+Grandfather signal is git-history first-appearance date
+(`git log --diff-filter=A`) compared against the topology paper's acceptance
+date (2026-05-26). Filesystem mtime is not used — it does not survive clone
+or touch.
+
+Mechanism: structural grep over ADR D-text for the artifact's path. No LLM.
+"""
+
+from __future__ import annotations
+
+import re
+import subprocess
+from datetime import date
+from pathlib import Path
+
+from .base import CoherenceCandidate
+
+
+_TOPOLOGY_ACCEPTANCE = date(2026, 5, 26)
+_STATUS_ACCEPTED = re.compile(
+    r"^\*\*Status:\*\*\s*Accepted", re.IGNORECASE | re.MULTILINE
+)
+_META_PARTS = {"META"}
+
+
+# ID: a7968f92-b6b9-4d0d-bb5d-6e6a7a6a4d43
+class Row4NamingCheck:
+    """Emit ROW4_NAMING for post-topology artifacts not named in any accepted ADR."""
+
+    relation = "ROW4_NAMING"
+
+    # ID: 99603b79-9830-4568-98bc-c59d9f5eb676
+    def __init__(self, repo_root: Path) -> None:
+        self._repo_root = Path(repo_root)
+
+    # ID: 809cc4b0-5fd8-47f0-a29d-930848b6e279
+    async def run(self) -> list[CoherenceCandidate]:
+        intent = self._repo_root / ".intent"
+        if not intent.is_dir():
+            return []
+        accepted_adr_texts = self._collect_accepted_adr_text()
+        candidates: list[CoherenceCandidate] = []
+        for path in _iter_intent_artifacts(intent):
+            rel = str(path.relative_to(self._repo_root))
+            if any(rel in text for text in accepted_adr_texts):
+                continue
+            first_seen = self._git_first_seen(rel)
+            if first_seen is not None and first_seen < _TOPOLOGY_ACCEPTANCE:
+                continue
+            candidates.append(
+                CoherenceCandidate(
+                    relation=self.relation,
+                    documents=[rel],
+                    claim=(
+                        f"`.intent/` artifact `{rel}` is not named in any accepted "
+                        "ADR's D-text and post-dates topology paper acceptance "
+                        "(2026-05-26)."
+                    ),
+                    rationale=(
+                        "Topology paper §3 row 4 strict requires every governance "
+                        "change in `.intent/` to be named in its governing ADR's "
+                        "D-text at acceptance. Grandfather exemption applies only "
+                        "to artifacts whose git first-appearance precedes topology "
+                        "acceptance. Either author the governing ADR (or amend an "
+                        "existing one) to reference this path, or — if the artifact "
+                        "is in fact pre-acceptance — verify the git history claim."
+                    ),
+                )
+            )
+        return candidates
+
+    def _collect_accepted_adr_text(self) -> list[str]:
+        decisions = self._repo_root / ".specs" / "decisions"
+        if not decisions.is_dir():
+            return []
+        texts: list[str] = []
+        for adr in sorted(decisions.glob("ADR-*.md")):
+            content = adr.read_text(encoding="utf-8", errors="replace")
+            if _STATUS_ACCEPTED.search(content):
+                texts.append(content)
+        return texts
+
+    def _git_first_seen(self, rel_path: str) -> date | None:
+        try:
+            result = subprocess.run(
+                [
+                    "git",
+                    "-C",
+                    str(self._repo_root),
+                    "log",
+                    "--diff-filter=A",
+                    "--format=%aI",
+                    "--",
+                    rel_path,
+                ],
+                capture_output=True,
+                text=True,
+                timeout=15,
+                check=False,
+            )
+        except (OSError, subprocess.TimeoutExpired):
+            return None
+        if result.returncode != 0 or not result.stdout.strip():
+            return None
+        last_line = result.stdout.strip().splitlines()[-1]
+        try:
+            return date.fromisoformat(last_line[:10])
+        except ValueError:
+            return None
+
+
+def _iter_intent_artifacts(intent_root: Path):
+    for path in sorted(intent_root.rglob("*")):
+        if not path.is_file():
+            continue
+        if _META_PARTS.intersection(path.parts):
+            continue
+        if path.suffix.lower() not in {".json", ".yaml", ".yml"}:
+            continue
+        yield path

mind/coherence/checks/sameconcern.py

@@ -0,0 +1,136 @@
+# src/mind/coherence/checks/sameconcern.py
+"""SAMECONCERN — §6.1 same-concern contradiction via vector kNN + LLM judge.
+
+Per ADR-073 D5 tiered cosine policy. Refuses if governance_claims is not
+seeded (per D4 governor-CLI bootstrap posture).
+
+Mechanism:
+  1. For each claim in the corpus, embed and kNN-search governance_claims.
+  2. Tier each hit: high-confidence (≥0.78), ambiguous (0.74-0.78), drop (<0.74).
+  3. Forward both tiers to the LLM judge (ambiguous tier gets a different prompt).
+  4. Dedupe pairs across the bi-directional iteration.
+
+Cosine thresholds are tunable per D5 telemetry feedback; defaults live here.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+from shared.logger import getLogger
+
+from ..llm_judge import judge_contradiction_pair
+from .base import CoherenceCandidate
+
+
+if TYPE_CHECKING:
+    from body.services.governance_claims_service import GovernanceClaimsService
+    from shared.governance.coherence_harvester import NormativeMarkerRegister
+
+
+logger = getLogger(__name__)
+
+
+_HIGH_CONFIDENCE_COSINE = 0.78
+_AMBIGUOUS_COSINE = 0.74
+_KNN_LIMIT = 10
+_DEFAULT_MAX_QUERIES = 200
+
+
+# ID: 5be96f7c-4c2b-4946-819a-b118b0535e19
+class SameConcernCheck:
+    """Emit SAMECONCERN candidates for contradicting pairs flagged by kNN + LLM."""
+
+    relation = "SAMECONCERN"
+
+    # ID: b34dfca3-3cb3-49e6-97c1-cd65bfdeb228
+    def __init__(
+        self,
+        repo_root: Path,
+        register: NormativeMarkerRegister,
+        claims_service: GovernanceClaimsService,
+        cognitive_service: Any,
+        max_queries: int | None = _DEFAULT_MAX_QUERIES,
+    ) -> None:
+        self._repo_root = Path(repo_root)
+        self._register = register
+        self._claims_service = claims_service
+        self._cognitive_service = cognitive_service
+        self._max_queries = max_queries
+
+    # ID: 43f12752-e72e-43e4-9d87-027d762e4e9e
+    async def run(self) -> list[CoherenceCandidate]:
+        from shared.governance.coherence_harvester import GovernanceClaimHarvester
+        from shared.infrastructure.vector.cognitive_adapter import (
+            CognitiveEmbedderAdapter,
+        )
+
+        if not await self._claims_service.is_seeded():
+            logger.info(
+                "SAMECONCERN: governance_claims collection not seeded; "
+                "skipping (run `core-admin coherence seed bootstrap` per D4)"
+            )
+            return []
+
+        harvester = GovernanceClaimHarvester(self._repo_root, self._register)
+        claims = list(harvester.harvest())
+        if self._max_queries is not None and len(claims) > self._max_queries:
+            import random
+
+            random.seed(42)
+            claims = random.sample(claims, self._max_queries)
+
+        embedder = CognitiveEmbedderAdapter(self._cognitive_service)
+        seen: set[frozenset[tuple[str, str]]] = set()
+        candidates: list[CoherenceCandidate] = []
+
+        for claim in claims:
+            try:
+                vector = await embedder.get_embedding(claim.text)
+            except Exception as exc:
+                logger.warning("SAMECONCERN: embed failed for query claim: %s", exc)
+                continue
+
+            hits = await self._claims_service.search(
+                query_vector=vector,
+                limit=_KNN_LIMIT,
+                score_threshold=_AMBIGUOUS_COSINE,
+            )
+
+            for hit in hits:
+                if (
+                    hit.source_path == claim.source_path
+                    and hit.content_sha == claim.content_sha
+                ):
+                    continue
+                tier = (
+                    "high_confidence"
+                    if hit.cosine >= _HIGH_CONFIDENCE_COSINE
+                    else "ambiguous"
+                )
+                pair_key: frozenset[tuple[str, str]] = frozenset(
+                    {
+                        (claim.source_path, claim.content_sha),
+                        (hit.source_path, hit.content_sha),
+                    }
+                )
+                if pair_key in seen:
+                    continue
+                seen.add(pair_key)
+
+                verdict = await judge_contradiction_pair(
+                    cognitive_service=self._cognitive_service,
+                    text_a=claim.text,
+                    source_a=claim.source_path,
+                    text_b=hit.text,
+                    source_b=hit.source_path,
+                    tier=tier,
+                    relation=self.relation,
+                    category_a=claim.category,
+                    category_b=hit.category,
+                )
+                if verdict is not None:
+                    candidates.append(verdict)
+
+        return candidates

mind/coherence/checks/specgap.py

@@ -0,0 +1,233 @@
+# src/mind/coherence/checks/specgap.py
+"""SPECGAP — upstream normative claim with no downstream operationalizing artifact.
+
+Per ADR-073 D7 + D11. Detects gaps where Northstar (or paper) declares a
+required behavior that the corresponding phase YAML's failure_mode does not
+address. Vector kNN cannot detect this class — the conflict is absence, not
+opposition.
+
+v1 detection rule per D7:
+  For each pair (N, P) where N is a Northstar/paper paragraph and P is a
+  workflow phase, emit when ALL of:
+    1. N qualifies as upstream-normative
+    2. N is operationally linked to P (D11 bridge or textual mention)
+    3. N contains a required-behavior action verb from D10
+    4. The phase YAML exists with a non-empty failure_mode
+    5. No failure_mode value overlaps the action-verb signal
+
+No LLM. No vectors.
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+import yaml
+
+from .base import CoherenceCandidate
+
+
+if TYPE_CHECKING:
+    from shared.governance.coherence_harvester import NormativeMarkerRegister
+
+
+_UR_HEADING = re.compile(r"^###\s+(UR-\d{2}):\s*(.+?)\s*$", re.MULTILINE)
+
+
+# ID: 8a9fd6fc-ce33-4b47-ba55-fe24b5d37bc5
+def _phases() -> tuple[str, ...]:
+    """Canonical `phase` membership from .intent/META/enums.json.
+
+    Sourced from the canonical enum store rather than inlined here so
+    SpecGap's iteration order tracks the constitutional vocabulary
+    without drift (closed-enum discipline, issue #460). Lazy because
+    coherence checks are constructed before IntentRepository may be
+    fully warm during cold-start scans.
+    """
+    from shared.infrastructure.intent.canonical_enums import get_enum_members
+
+    return tuple(sorted(get_enum_members("phase")))
+
+
+# ID: 462e86d4-ce44-4239-8fb0-4efaf0a5278d
+class SpecGapCheck:
+    """Emit SPECGAP when upstream required behavior has no downstream operationalization."""
+
+    relation = "SPECGAP"
+
+    # ID: 9fb8fe6c-ae8c-4be5-9022-fc6c4ac0c362
+    def __init__(self, repo_root: Path, register: NormativeMarkerRegister) -> None:
+        self._repo_root = Path(repo_root)
+        self._register = register
+        self._action_verb_pattern = re.compile(
+            "|".join(rf"\b{re.escape(v)}\w*\b" for v in register.action_verbs),
+            re.IGNORECASE,
+        )
+
+    # ID: 43197388-342a-495c-844f-2889159e9994
+    async def run(self) -> list[CoherenceCandidate]:
+        phase_modes = self._load_phase_failure_modes()
+        responsibility = self._load_phase_responsibility()
+        ur_paragraphs = self._extract_ur_paragraphs()
+
+        candidates: list[CoherenceCandidate] = []
+        for ur_id, ur_rel, paragraph in ur_paragraphs:
+            action_verbs = self._action_verbs_in(paragraph)
+            if not action_verbs:
+                continue
+            for phase in _phases():
+                if not self._operationally_linked(
+                    ur_id, paragraph, phase, responsibility
+                ):
+                    continue
+                failure_modes = phase_modes.get(phase) or {}
+                if not failure_modes:
+                    continue
+                if self._verbs_covered_by(failure_modes):
+                    continue
+                phase_rel = f".intent/phases/{phase}.yaml"
+                rendered = ", ".join(
+                    f"{cls}:{strat}" for cls, strat in sorted(failure_modes.items())
+                )
+                candidates.append(
+                    CoherenceCandidate(
+                        relation=self.relation,
+                        documents=[ur_rel, phase_rel],
+                        claim=(
+                            f"Northstar §{ur_id} declares required behavior "
+                            f"({', '.join(sorted(action_verbs))}) for phase "
+                            f"`{phase}`, but `{phase}.yaml`'s failure_modes "
+                            f"({rendered}) do not address it."
+                        ),
+                        rationale=(
+                            f"Topology paper §6.1 contradiction invariant via "
+                            f"the D11 phase-responsibility bridge identifies "
+                            f"`{phase}` as responsible for {ur_id}. The Northstar "
+                            f"paragraph asserts the system should "
+                            f"{', '.join(sorted(action_verbs))} under some condition, "
+                            f"but the phase declares failure_modes "
+                            f"({rendered}) — neither the failure-class names "
+                            f"nor the response-strategy values match a halt-class "
+                            "action verb. Either extend the phase's failure_modes "
+                            "to cover the upstream required behavior (ADR-074 D2 "
+                            "map shape), or — if the upstream claim is no longer "
+                            "authoritative — amend Northstar."
+                        ),
+                    )
+                )
+        return candidates
+
+    def _load_phase_failure_modes(self) -> dict[str, dict[str, str]]:
+        """Return per-phase failure-class → response-strategy map (ADR-074 D2).
+
+        Reads `.intent/phases/<phase>.yaml` and returns the `failure_modes:`
+        mapping. Returns an empty dict for the phase if the file is missing
+        or declares no `failure_modes`. Legacy scalar `failure_mode:` keys
+        are intentionally not read — ADR-074 D12 retires the singular field.
+        """
+        result: dict[str, dict[str, str]] = {}
+        for phase in _phases():
+            path = self._repo_root / ".intent" / "phases" / f"{phase}.yaml"
+            if not path.exists():
+                result[phase] = {}
+                continue
+            data = yaml.safe_load(path.read_text(encoding="utf-8")) or {}
+            modes = data.get("failure_modes")
+            if isinstance(modes, dict):
+                result[phase] = {str(k): str(v) for k, v in modes.items()}
+            else:
+                result[phase] = {}
+        return result
+
+    def _load_phase_responsibility(self) -> dict[str, dict]:
+        path = (
+            self._repo_root
+            / ".intent"
+            / "enforcement"
+            / "config"
+            / "phase_responsibility.yaml"
+        )
+        if not path.exists():
+            return {}
+        data = yaml.safe_load(path.read_text(encoding="utf-8")) or {}
+        return data.get("phases", {}) or {}
+
+    def _extract_ur_paragraphs(self) -> list[tuple[str, str, str]]:
+        path = self._repo_root / ".specs" / "northstar" / "CORE-USER-REQUIREMENTS.md"
+        if not path.exists():
+            return []
+        content = path.read_text(encoding="utf-8")
+        rel = str(path.relative_to(self._repo_root))
+        matches = list(_UR_HEADING.finditer(content))
+        result: list[tuple[str, str, str]] = []
+        for i, m in enumerate(matches):
+            ur_id = m.group(1)
+            start = m.end()
+            end = matches[i + 1].start() if i + 1 < len(matches) else len(content)
+            section = content[start:end]
+            for paragraph in _iter_paragraphs(section):
+                result.append((ur_id, rel, paragraph))
+        return result
+
+    # ID: b891e1a5-db39-4243-a3e9-79f5425e8bdc
+    def _operationally_linked(
+        self,
+        ur_id: str,
+        paragraph: str,
+        phase: str,
+        responsibility: dict[str, dict],
+    ) -> bool:
+        """D7 condition 2: phase mentioned in text OR linked via D11 mapping."""
+        phase_entry = responsibility.get(phase) or {}
+        if phase_entry.get("cross_cutting"):
+            return False
+        urs = phase_entry.get("operationalizes_urs") or []
+        if ur_id in urs:
+            return True
+        return _whole_word(paragraph, phase) or _whole_word(paragraph, phase + "s")
+
+    def _action_verbs_in(self, text: str) -> set[str]:
+        verbs: set[str] = set()
+        for m in self._action_verb_pattern.finditer(text):
+            verbs.add(m.group(0).lower())
+        return verbs
+
+    # ID: 4b4328d6-4874-4d40-87b8-123c510da8ce
+    def _verbs_covered_by(self, failure_modes: dict[str, str]) -> bool:
+        """Covered iff any failure-class key OR response-strategy value declares an action verb.
+
+        Per ADR-074 D9: a phase addresses an upstream halt-class signal when
+        either the failure-class name (e.g., `contradiction`) or the
+        response-strategy value (e.g., `block`) string-matches a verb from
+        the normative-marker register. Map keys and values are both checked
+        because either signal independently operationalizes the upstream
+        required behavior.
+        """
+        for key, value in failure_modes.items():
+            if self._action_verb_pattern.search(key):
+                return True
+            if self._action_verb_pattern.search(value):
+                return True
+        return False
+
+
+def _iter_paragraphs(section: str):
+    para: list[str] = []
+    for line in section.split("\n"):
+        if line.strip():
+            para.append(line)
+        elif para:
+            text = "\n".join(para).strip()
+            if text:
+                yield text
+            para = []
+    if para:
+        text = "\n".join(para).strip()
+        if text:
+            yield text
+
+
+def _whole_word(content: str, token: str) -> bool:
+    return re.search(rf"\b{re.escape(token)}\b", content, re.IGNORECASE) is not None