marvisx-cli 0.1.0__py3-none-any.whl

core/api/services/brain/rules/dr5_playbook_changed.py

@@ -0,0 +1,99 @@
+# DR5 — Procedure / Playbook Changed (sub-02 §5 DR5, CE4 axis=context).
+# If a handoff_changed/learning_changed event's summary matches the compiled
+# procedure regex AND no playbook/guide artifact updated in the same cycle,
+# emit `playbook_changed`.
+#
+# CycleSnapshot pre-filters procedure_keyword_hits — scan ONLY summary text
+# of digest events. NEVER read handoff files from disk (anti-pattern).
+from __future__ import annotations
+
+from datetime import datetime
+
+from core.api.models.brain import DriftSignal
+from core.api.services.brain.cycle_snapshot import CycleSnapshot
+from core.api.services.brain.rules._signals import build_signal
+
+
+_ELIGIBLE_EVENT_TYPES = frozenset({"handoff_changed", "learning_changed"})
+
+
+def _has_playbook_artifact_updated(snapshot: CycleSnapshot) -> bool:
+    """Check if any doc_changed event in this cycle is a playbook/guide."""
+    for ev in snapshot.by_event_type.get("doc_changed", []):
+        ref = ev.source_ref.lower()
+        if "playbook" in ref or "guide" in ref:
+            return True
+        if isinstance(ev.evidence, dict):
+            kind = ev.evidence.get("kind")
+            if isinstance(kind, str) and kind in {"playbook", "guide"}:
+                return True
+    return False
+
+
+async def build_signals(
+    snapshot: CycleSnapshot, *, run_id: str, now: datetime
+) -> list[DriftSignal]:
+    signals: list[DriftSignal] = []
+    if not snapshot.procedure_keyword_hits:
+        return signals
+    playbook_updated = _has_playbook_artifact_updated(snapshot)
+    if playbook_updated:
+        return signals
+
+    seen_refs: set[str] = set()
+    for event in snapshot.procedure_keyword_hits:
+        if event.event_type not in _ELIGIBLE_EVENT_TYPES:
+            continue
+        if event.source_ref in seen_refs:
+            continue
+        seen_refs.add(event.source_ref)
+
+        if event.source_project:
+            scope_type, scope_key = "project", event.source_project
+        elif event.program_key:
+            scope_type, scope_key = "program", event.program_key
+        else:
+            scope_type, scope_key = "company", "__company__"
+
+        involved_projects = sorted(
+            {
+                p
+                for p in (event.source_project, event.target_project)
+                if isinstance(p, str) and p
+            }
+        )
+        modifiers = 0
+        if len(involved_projects) > 1:
+            modifiers += 1
+
+        observed_ref = f"event:{event.event_id}"
+        observed_delta = (
+            f"Procedure-change summary in {event.source_ref} ({event.event_type}) "
+            f"without matching playbook/guide update."
+        )
+        signals.append(
+            build_signal(
+                run_id=run_id,
+                cycle_key=snapshot.cycle_key,
+                detected_at=now,
+                rule_id="DR5",
+                scope_type=scope_type,  # type: ignore[arg-type]
+                scope_key=scope_key,
+                program_key=event.program_key,
+                signal_type="playbook_changed",
+                expected_direction_source="doc",
+                expected_direction_ref=None,
+                observed_direction_ref=observed_ref,
+                observed_delta=observed_delta,
+                evidence_refs=[observed_ref],
+                severity_base="high",
+                drift_axis="context",
+                involved_projects=involved_projects,
+                severity_modifiers=modifiers,
+                observed_event=event,
+            )
+        )
+    return signals
+
+
+__all__ = ["build_signals"]

core/api/services/brain/rules/dr6_external_update_unpropagated.py

@@ -0,0 +1,100 @@
+# DR6 — External Update Unpropagated (sub-02 §5 DR6, CE4 axis=context).
+# If `external_update_seen` event has no linked internal artifact within
+# `brain_drift_propagation_window_cycles` (default 3), emit
+# `external_update_unpropagated`. Severity escalates per missed cycle.
+#
+# v1.01 note: external_update_seen producer is deferred (sub-01 §3). DR6 will
+# be a no-op until that producer ships — tests treat it accordingly.
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any
+
+from core.api.models.brain import DriftSignal, Severity
+from core.api.services.brain.cycle_snapshot import CycleSnapshot, DigestEventRow
+from core.api.services.brain.rules._signals import build_signal
+
+# Severity ladder: medium → high @ 2 missed cycles → critical @ 3+ (max).
+def _severity_for_missed(missed: int) -> Severity:
+    if missed >= 3:
+        return "critical"
+    if missed >= 2:
+        return "high"
+    return "medium"
+
+
+def _propagation_linked(event: DigestEventRow) -> bool:
+    if not isinstance(event.evidence, dict):
+        return False
+    if event.evidence.get("propagation_link_ref"):
+        return True
+    linked = event.evidence.get("linked_artifacts")
+    if isinstance(linked, list) and linked:
+        return True
+    return False
+
+
+def _scope(event: DigestEventRow) -> tuple[str, str]:
+    if event.source_project:
+        return ("project", event.source_project)
+    if event.program_key:
+        return ("program", event.program_key)
+    return ("company", "__company__")
+
+
+async def build_signals(
+    snapshot: CycleSnapshot, *, run_id: str, now: datetime
+) -> list[DriftSignal]:
+    signals: list[DriftSignal] = []
+    seen_refs: set[str] = set()
+    for event in snapshot.external_update_events:
+        if _propagation_linked(event):
+            continue
+        if event.source_ref in seen_refs:
+            continue
+        seen_refs.add(event.source_ref)
+
+        scope_type, scope_key = _scope(event)
+        observed_ref = f"event:{event.event_id}"
+        # Missed cycles: derived from evidence if available, else default 1.
+        missed = 1
+        if isinstance(event.evidence, dict):
+            raw = event.evidence.get("missed_cycles")
+            if isinstance(raw, int) and raw > 0:
+                missed = min(raw, 5)
+        severity_base = _severity_for_missed(missed)
+        observed_delta = (
+            f"External update {event.source_ref} observed without internal "
+            f"propagation (missed {missed} cycle(s))."
+        )
+        signals.append(
+            build_signal(
+                run_id=run_id,
+                cycle_key=snapshot.cycle_key,
+                detected_at=now,
+                rule_id="DR6",
+                scope_type=scope_type,  # type: ignore[arg-type]
+                scope_key=scope_key,
+                program_key=event.program_key,
+                signal_type="external_update_unpropagated",
+                expected_direction_source="none",
+                expected_direction_ref=None,
+                observed_direction_ref=observed_ref,
+                observed_delta=observed_delta,
+                evidence_refs=[observed_ref],
+                severity_base=severity_base,
+                drift_axis="context",
+                involved_projects=sorted(
+                    {
+                        p
+                        for p in (event.source_project, event.target_project)
+                        if isinstance(p, str) and p
+                    }
+                ),
+                observed_event=event,
+            )
+        )
+    return signals
+
+
+__all__ = ["build_signals"]

core/api/services/brain/rules/dr7_claimed_decision_gap.py

@@ -0,0 +1,123 @@
+# DR7 — Claimed Decision Gap (sub-02 §5 DR7, CE4 axis=intent).
+# If an event has decision_marker in {approved, signed_off} AND no matching
+# audit_log row with actor_user_id IS NOT NULL referencing the same artifact,
+# emit `claimed_decision_gap`. Severity high; critical if claim is external.
+#
+# Cross-reference: rogue-agent-creates-task-and-PR learning (2026-05-12).
+from __future__ import annotations
+
+import logging
+from datetime import datetime
+
+from core.api.db import acquire_db
+from core.api.models.brain import DriftSignal
+from core.api.services.brain.cycle_snapshot import CycleSnapshot, DigestEventRow
+from core.api.services.brain.rules._signals import build_signal
+
+logger = logging.getLogger(__name__)
+
+_CLAIM_MARKERS = frozenset({"approved", "signed_off"})
+
+
+async def _audit_lookup(source_refs: list[str]) -> set[str]:
+    """Return the subset of source_refs that have a human-actor audit row."""
+    if not source_refs:
+        return set()
+    placeholders = ",".join("?" for _ in source_refs)
+    try:
+        async with acquire_db() as db:
+            cursor = await db.execute(
+                f"SELECT DISTINCT entity_ref FROM audit_log "
+                f"WHERE entity_ref IN ({placeholders}) "
+                f"AND actor_user_id IS NOT NULL",
+                source_refs,
+            )
+            rows = await cursor.fetchall()
+    except Exception as exc:  # noqa: BLE001 — table may not exist
+        logger.debug("DR7: audit_log lookup skipped (%s)", exc)
+        return set()
+    return {row[0] for row in rows}
+
+
+def _scope(event: DigestEventRow) -> tuple[str, str]:
+    if event.source_project:
+        return ("project", event.source_project)
+    if event.program_key:
+        return ("program", event.program_key)
+    return ("company", "__company__")
+
+
+async def build_signals(
+    snapshot: CycleSnapshot, *, run_id: str, now: datetime
+) -> list[DriftSignal]:
+    candidates: list[tuple[DigestEventRow, str]] = []
+    for event in snapshot.decision_marker_events:
+        marker = event.evidence.get("decision_marker") if isinstance(event.evidence, dict) else None
+        if not isinstance(marker, str) or marker not in _CLAIM_MARKERS:
+            continue
+        candidates.append((event, event.source_ref))
+    if not candidates:
+        return []
+
+    # Batched lookup (chunked IN, max 500 per chunk — §5 DR7).
+    refs = [src_ref for _, src_ref in candidates]
+    matched: set[str] = set()
+    chunk = 500
+    for i in range(0, len(refs), chunk):
+        matched |= await _audit_lookup(refs[i : i + chunk])
+
+    signals: list[DriftSignal] = []
+    seen: set[str] = set()
+    for event, src_ref in candidates:
+        if src_ref in matched:
+            continue
+        if src_ref in seen:
+            continue
+        seen.add(src_ref)
+        scope_type, scope_key = _scope(event)
+        observed_ref = f"event:{event.event_id}"
+        marker = (
+            event.evidence.get("decision_marker")
+            if isinstance(event.evidence, dict)
+            else "approved"
+        )
+        observed_delta = (
+            f"Decision claim '{marker}' on {src_ref} with no human actor in audit_log."
+        )
+        external = bool(
+            isinstance(event.evidence, dict)
+            and event.evidence.get("claimed_by_external")
+        )
+        severity_base = "critical" if external else "high"
+        signals.append(
+            build_signal(
+                run_id=run_id,
+                cycle_key=snapshot.cycle_key,
+                detected_at=now,
+                rule_id="DR7",
+                scope_type=scope_type,  # type: ignore[arg-type]
+                scope_key=scope_key,
+                program_key=event.program_key,
+                signal_type="claimed_decision_gap",
+                expected_direction_source="none",
+                expected_direction_ref=None,
+                observed_direction_ref=observed_ref,
+                observed_delta=observed_delta,
+                evidence_refs=[observed_ref, f"audit_query:{src_ref}"],
+                severity_base=severity_base,
+                drift_axis="intent",
+                involved_projects=sorted(
+                    {
+                        p
+                        for p in (event.source_project, event.target_project)
+                        if isinstance(p, str) and p
+                    }
+                ),
+                observed_event=event,
+                decision_marker=marker if isinstance(marker, str) else None,
+            )
+        )
+    return signals
+
+
+__all__ = ["build_signals"]

core/api/services/brain/rules/dr8_direction_misalignment.py

@@ -0,0 +1,230 @@
+# DR8 — Direction Misalignment (Brain v1.2, signal_type=direction_misalignment,
+# axis=intent).
+#
+# Compares the project's declared direction (project_directions.summary +
+# out_of_scope) against the events observed in the cycle. Emits a drift signal
+# when the LLM classifier (tier-fast Gemma 4 E4B) reports status != aligned
+# with confidence >= 0.85.
+#
+# If no direction record is present for the project, the rule is a no-op
+# (returns []). Bootstrap phase populates direction via the bootstrap-apply
+# script + Console Triage approval workflow.
+#
+# Pragmatic v1 implementation (without live tier-fast call):
+#   * Hard-codes a deterministic heuristic for tests: emit a high-confidence
+#     `direction_misalignment` signal when `events_count >= ACTIVITY_MIN` AND
+#     the project has a direction row. The orchestrator then derives the
+#     observed_delta + proposed_payload via the upstream LLM call when
+#     enabled (env BRAIN_DR8_LLM_ENABLED=true).
+#   * LLM polish for proposed_direction_update is invoked asynchronously
+#     via api.services.brain.llm.* (existing tier-write provider). If LLM
+#     unavailable, the signal is still emitted with a deterministic
+#     observed_delta and no proposed_payload.
+#
+# Decisione brainstorm §6: NO banned-words retry policy on the LLM prompt.
+
+from __future__ import annotations
+
+import logging
+import os
+from datetime import datetime
+from typing import Any
+
+import aiosqlite
+
+from core.api.db import acquire_db
+from core.api.models.brain import DriftSignal
+from core.api.services.brain.cycle_snapshot import CycleSnapshot, DigestEventRow
+from core.api.services.brain.rules._signals import build_signal
+
+logger = logging.getLogger(__name__)
+
+ACTIVITY_MIN = 1  # any event vs declared direction triggers DR8 evaluation
+CONFIDENCE_EMIT_THRESHOLD = 0.85
+
+
+async def _fetch_directions(
+    *, db: aiosqlite.Connection
+) -> dict[str, dict[str, Any]]:
+    """Fetch every project_directions row keyed by project_slug."""
+    cur = await db.execute(
+        "SELECT project_slug, summary, out_of_scope, last_updated_at"
+        " FROM project_directions"
+    )
+    rows = await cur.fetchall()
+    await cur.close()
+    out: dict[str, dict[str, Any]] = {}
+    for row in rows:
+        slug = row[0]
+        out[slug] = {
+            "summary": row[1],
+            "out_of_scope": row[2],
+            "last_updated_at": row[3],
+        }
+    return out
+
+
+def _events_evidence_refs(events: list[DigestEventRow], cap: int = 5) -> list[str]:
+    """Pick up to `cap` event refs (commits, tasks, prs, handoffs) as evidence."""
+    refs: list[str] = []
+    for ev in events[:cap]:
+        if ev.source_ref:
+            refs.append(f"{ev.source_system or 'event'}:{ev.source_ref}")
+    return refs
+
+
+def _summarise_events(events: list[DigestEventRow]) -> str:
+    """Build a short observed-delta string from events."""
+    if not events:
+        return "no events in cycle window"
+    counters: dict[str, int] = {}
+    for ev in events:
+        kind = ev.event_type or "event"
+        counters[kind] = counters.get(kind, 0) + 1
+    parts = sorted(counters.items(), key=lambda kv: -kv[1])[:5]
+    return "events_in_cycle: " + ", ".join(f"{k}={v}" for k, v in parts)
+
+
+async def build_signals(
+    snapshot: CycleSnapshot, *, run_id: str, now: datetime
+) -> list[DriftSignal]:
+    """Emit DR8 direction_misalignment signals for projects with declared direction.
+
+    Strategy:
+      1. Load all project_directions rows (DB cache, fast SQL).
+      2. For each (project_scope, scope_key=slug) in CycleSnapshot.by_scope,
+         if a direction is present AND events_count >= ACTIVITY_MIN:
+           - Build deterministic observed_delta from events summary.
+           - Confidence defaults to 0.6 (heuristic). When LLM enabled (env
+             BRAIN_DR8_LLM_ENABLED=true), tier-fast classifier may bump to
+             >= 0.85 → emit. Without LLM, signals stay below threshold but
+             are still recorded (`state='open'`) so the orchestrator can
+             surface them for later promotion.
+      3. The CONFIDENCE_FLOOR enforcement happens upstream; we only need to
+         emit signals with confidence >= CONFIDENCE_EMIT_THRESHOLD to drive
+         L5 finding creation.
+
+    Returns drift signals (empty list when no direction or no events).
+    """
+    signals: list[DriftSignal] = []
+
+    async with acquire_db() as db:
+        directions = await _fetch_directions(db=db)
+
+    if not directions:
+        logger.debug("DR8: no project_directions rows — skipping")
+        return signals
+
+    llm_enabled = os.environ.get("BRAIN_DR8_LLM_ENABLED", "").lower() in (
+        "1", "true", "yes",
+    )
+
+    for (scope_type, scope_key), events in snapshot.by_scope.items():
+        if scope_type != "project":
+            continue
+        direction = directions.get(scope_key)
+        if direction is None:
+            continue
+        if len(events) < ACTIVITY_MIN:
+            continue
+
+        observed_delta = _summarise_events(events)
+        evidence_refs = _events_evidence_refs(events)
+        expected_ref = f"project_directions:{scope_key}"
+        observed_ref = f"events_window:{scope_key}:{snapshot.cycle_key}"
+
+        # Confidence: deterministic baseline = 0.55 (medium).
+        # LLM-enabled path bumps to 0.9 when classifier returns status != aligned.
+        # Per brainstorm §6 we do NOT run a banned-words retry; the LLM result
+        # is accepted as-is.
+        confidence_estimate = 0.55
+        proposed_payload: dict[str, Any] | None = None
+
+        if llm_enabled:
+            # Lazy import — keep rule importable without LLM stack in tests.
+            try:
+                from core.api.services.brain.llm import get_brain_llm_service
+                # `get_brain_llm_service` is a sync singleton accessor — do NOT
+                # await it. The async surface is `llm.classify_direction_alignment`.
+                llm = get_brain_llm_service()
+                # Build prompt context — keep it compact (~2k tokens)
+                prompt_payload = {
+                    "project_slug": scope_key,
+                    "direction_summary": direction["summary"],
+                    "direction_out_of_scope": direction["out_of_scope"],
+                    "events_observed": observed_delta,
+                    "events_refs": evidence_refs,
+                }
+                # Reuse the polish surface — caller wraps result in PolishResult.
+                # If grounding fails we fall back to deterministic confidence.
+                result = await llm.classify_direction_alignment(prompt_payload)  # type: ignore[attr-defined]
+                if result is not None:
+                    confidence_estimate = float(result.get("confidence", 0.55))
+                    if result.get("status") and result.get("status") != "aligned":
+                        proposed_payload = {
+                            "status": result.get("status"),
+                            "rationale": result.get("rationale", ""),
+                            "proposed_summary": result.get("proposed_summary"),
+                            "proposed_out_of_scope": result.get("proposed_out_of_scope"),
+                        }
+            except Exception as exc:  # noqa: BLE001 — LLM is best-effort
+                logger.warning(
+                    "DR8: LLM classify failed for %s: %s — fallback heuristic",
+                    scope_key, exc,
+                )
+
+        # Emit signal regardless of confidence — L5 findings layer filters
+        # by >= 0.85; signals < 0.85 stay as audit-only rows.
+        program_key = None
+        try:
+            project_meta = snapshot.project_meta.get(scope_key, {})  # type: ignore[attr-defined]
+            program_key = project_meta.get("program")
+        except (AttributeError, Exception):  # pragma: no cover
+            program_key = None
+
+        signal = build_signal(
+            run_id=run_id,
+            cycle_key=snapshot.cycle_key,
+            detected_at=now,
+            rule_id="DR8",
+            scope_type="project",
+            scope_key=scope_key,
+            program_key=program_key,
+            signal_type="direction_misalignment",
+            expected_direction_source="doc",
+            expected_direction_ref=expected_ref,
+            observed_direction_ref=observed_ref,
+            observed_delta=observed_delta,
+            evidence_refs=evidence_refs or [expected_ref],
+            severity_base="medium",
+            drift_axis="intent",
+            involved_projects=[scope_key],
+        )
+        # Override the heuristic confidence with our LLM-aware estimate.
+        # `build_signal` already clamps to [FLOOR, 1.0].
+        signal_dict = signal.model_dump()
+        signal_dict["confidence"] = max(0.3, min(1.0, confidence_estimate))
+        signal = type(signal)(**signal_dict)
+
+        # Attach proposed_payload via evidence_json passthrough — orchestrator
+        # writes it to brain_drift_signals.evidence_json so L5 can read it.
+        if proposed_payload is not None:
+            try:
+                import json as _json
+                # Mutate the signal's evidence to include the proposed payload
+                # under a reserved key the L5 layer recognises. This stays
+                # backward-compatible (older rules emit list[str] evidence).
+                signal_dict = signal.model_dump()
+                ev = list(signal_dict.get("evidence", []))
+                ev.append(f"proposed_payload_json:{_json.dumps(proposed_payload, sort_keys=True)}")
+                signal_dict["evidence"] = ev
+                signal = type(signal)(**signal_dict)
+            except Exception:  # pragma: no cover
+                pass
+
+        signals.append(signal)
+
+    return signals
+
+
+__all__ = ["build_signals", "ACTIVITY_MIN", "CONFIDENCE_EMIT_THRESHOLD"]