arkaos 2.31.0 → 2.40.0

package/core/governance/dod_gate.py

@@ -0,0 +1,192 @@
+"""Definition of Done gate for ArkaOS deliveries (PR14 v2.36.0).
+
+Implements the `definition-of-done-per-domain` NON-NEGOTIABLE rule from
+PR10 constitution. Loads the per-domain checklists from
+``config/constitution.yaml`` (`definition_of_done` section) and evaluates
+an agent-supplied status report against them.
+
+The gate does NOT execute the underlying checks itself (e.g. it does not
+run Playwright or lint). It validates that the agent has reported a
+status for each item in the relevant domain — passed, skipped, failed,
+or not-applicable — and produces a verdict.
+
+Hard items: ALL must be ``passed`` for the verdict to be APPROVED.
+Soft items: may be ``skipped`` without rejection, but a ``failed``
+soft item is still recorded.
+
+This mirrors the audit pattern used by Marta in QG: the agent presents
+its work + status claims, and the gate verifies completeness against
+the canonical checklist. False reporting is a different problem (the
+sycophancy detector + critic pass in QG catch that).
+"""
+
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass, field
+from pathlib import Path
+from typing import Literal
+
+import yaml
+
+ItemStatus = Literal["passed", "skipped", "failed", "not-applicable"]
+
+_CONSTITUTION_PATH = (
+    Path(__file__).resolve().parents[2] / "config" / "constitution.yaml"
+)
+
+_VALID_STATUSES: frozenset[str] = frozenset({
+    "passed", "skipped", "failed", "not-applicable",
+})
+
+
+@dataclass(frozen=True)
+class DODItem:
+    """One Definition-of-Done checklist item from the constitution."""
+
+    id: str
+    rule: str
+    hard: bool
+    conditional: str | None = None
+
+
+@dataclass
+class DODVerdict:
+    """Structured outcome of a DOD evaluation."""
+
+    domain: str
+    approved: bool
+    failed_hard_items: list[str] = field(default_factory=list)
+    failed_soft_items: list[str] = field(default_factory=list)
+    skipped_hard_items: list[str] = field(default_factory=list)
+    skipped_soft_items: list[str] = field(default_factory=list)
+    unreported_hard_items: list[str] = field(default_factory=list)
+    unreported_soft_items: list[str] = field(default_factory=list)
+    not_applicable: list[str] = field(default_factory=list)
+
+    def to_dict(self) -> dict:
+        return asdict(self)
+
+    def summary(self) -> str:
+        parts: list[str] = []
+        if self.approved:
+            parts.append("APPROVED")
+        else:
+            parts.append("REJECTED")
+        if self.failed_hard_items:
+            parts.append(f"failed-hard={','.join(self.failed_hard_items)}")
+        if self.unreported_hard_items:
+            parts.append(f"unreported-hard={','.join(self.unreported_hard_items)}")
+        if self.skipped_hard_items:
+            parts.append(f"skipped-hard={','.join(self.skipped_hard_items)}")
+        return " | ".join(parts)
+
+
+def load_definition_of_done(
+    domain: str, constitution_path: Path | None = None
+) -> list[DODItem]:
+    """Return the DOD items for *domain* (universal items + domain-specific).
+
+    ``domain`` is one of: ``frontend``, ``backend``, ``content``. Other
+    names raise ``ValueError`` (no implicit fallback — agents must opt
+    in to a known domain). Universal items are always merged in front
+    of the domain-specific items.
+    """
+    path = constitution_path or _CONSTITUTION_PATH
+    with open(path, encoding="utf-8") as fh:
+        data = yaml.safe_load(fh)
+    dod = data.get("definition_of_done") or {}
+    if domain not in dod or domain == "description" or domain == "universal":
+        valid = [
+            k for k in dod.keys()
+            if k not in {"description", "universal"}
+        ]
+        raise ValueError(
+            f"unknown DOD domain {domain!r}; choose from {sorted(valid)}"
+        )
+
+    items: list[DODItem] = []
+    for raw in (dod.get("universal", {}).get("items") or []):
+        items.append(_to_item(raw))
+    for raw in (dod[domain].get("items") or []):
+        items.append(_to_item(raw))
+    return items
+
+
+def evaluate_dod(
+    domain: str,
+    item_statuses: dict[str, str],
+    constitution_path: Path | None = None,
+) -> DODVerdict:
+    """Validate *item_statuses* against the DOD checklist for *domain*.
+
+    Inputs:
+      domain         — one of "frontend", "backend", "content"
+      item_statuses  — mapping {item_id: "passed"|"skipped"|"failed"|
+                      "not-applicable"} reported by the agent
+      constitution_path — optional override (test injection)
+
+    Returns a :class:`DODVerdict`. Verdict is APPROVED iff:
+      - every hard item is reported AND status == "passed"
+        (or "not-applicable" with explicit justification — recorded
+        but does not block)
+
+    Soft items: never block. Their statuses are recorded for telemetry.
+    Unknown status values raise ValueError.
+    """
+    items = load_definition_of_done(domain, constitution_path)
+    for status in item_statuses.values():
+        if status not in _VALID_STATUSES:
+            raise ValueError(
+                f"invalid status {status!r}; must be one of {sorted(_VALID_STATUSES)}"
+            )
+
+    verdict = DODVerdict(domain=domain, approved=True)
+    for item in items:
+        reported = item_statuses.get(item.id)
+        if reported is None:
+            if item.hard:
+                verdict.unreported_hard_items.append(item.id)
+                verdict.approved = False
+            else:
+                verdict.unreported_soft_items.append(item.id)
+            continue
+        if reported == "passed":
+            continue
+        if reported == "not-applicable":
+            verdict.not_applicable.append(item.id)
+            continue
+        if reported == "skipped":
+            if item.hard:
+                verdict.skipped_hard_items.append(item.id)
+                verdict.approved = False
+            else:
+                verdict.skipped_soft_items.append(item.id)
+            continue
+        if reported == "failed":
+            if item.hard:
+                verdict.failed_hard_items.append(item.id)
+                verdict.approved = False
+            else:
+                verdict.failed_soft_items.append(item.id)
+    return verdict
+
+
+def list_supported_domains(constitution_path: Path | None = None) -> list[str]:
+    """Enumerate the domains the constitution defines DOD checklists for."""
+    path = constitution_path or _CONSTITUTION_PATH
+    with open(path, encoding="utf-8") as fh:
+        data = yaml.safe_load(fh)
+    dod = data.get("definition_of_done") or {}
+    return sorted(
+        k for k in dod.keys()
+        if k not in {"description", "universal"}
+    )
+
+
+def _to_item(raw: dict) -> DODItem:
+    return DODItem(
+        id=str(raw["id"]),
+        rule=str(raw["rule"]),
+        hard=bool(raw.get("hard", True)),
+        conditional=raw.get("conditional"),
+    )

package/core/governance/kb_cite_check.py

@@ -0,0 +1,129 @@
+"""KB citation check for ArkaOS responses (PR18 v2.40.0).
+
+Soft-block classifier. Inspects an assistant response for KB
+citations (`[[wikilink]]`, `[knowledge:` marker, `file.ext:line`
+code references) and reports whether the response honored the
+KB-first contract on an ArkaOS topic.
+
+Non-blocking by design — hooks consume CitationResult and decide
+whether to surface a nudge to the next turn's additionalContext.
+This module never raises; on malformed input it returns a passed
+"trivial" verdict so the caller never crashes the hook pipeline.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+
+# ─── Patterns ───────────────────────────────────────────────────────────
+
+_WIKILINK_PATTERN: re.Pattern[str] = re.compile(r"\[\[([^\[\]]+)\]\]")
+_KNOWLEDGE_PATTERN: re.Pattern[str] = re.compile(r"\[knowledge:", re.IGNORECASE)
+# File:line — requires at least one path separator. Quantifiers are bounded
+# to prevent catastrophic backtracking on pathological input (PR18 security
+# review: unbounded variant blew past Stop's 5s budget by ~8x on 100KB of
+# `a/a/a/...` with no trailing extension).
+_FILE_LINE_PATTERN: re.Pattern[str] = re.compile(
+    r"(?:[\w._-]{1,64}/){1,8}[\w._-]{1,64}\.\w{1,8}:\d{1,6}"
+)
+# Hard upper bound on input scanned for citations. Anything beyond is
+# almost certainly a code dump / log paste and not human prose — skip the
+# more expensive file-line regex entirely above this threshold.
+_MAX_SCAN_CHARS: int = 50_000
+
+# ArkaOS topic keywords. Match is case-insensitive substring.
+_ARKAOS_KEYWORDS: frozenset[str] = frozenset({
+    "arkaos", "arka", "constitution", "quality gate", "synapse",
+    "conclave", "forge", "dreaming", "marta", "eduardo", "francisca",
+    "marco", "helena", "sofia", "paulo", "luna", "valentina",
+    "tomas", "ricardo", "clara", "daniel", "carolina", "tiago",
+    "ines", "rafael", "beatriz", "miguel", "rodrigo",
+    "non-negotiable", "tier 0", "squad lead",
+    "core/governance", "core/synapse", "core/cognition",
+    "core/workflow", "mcp__obsidian", "kb-first",
+    "departments/", "agent yaml", "obsidian vault",
+})
+
+_BYPASS_DEFAULTS: tuple[str, ...] = ("[arka:trivial]",)
+_TRIVIAL_WORD_THRESHOLD: int = 15
+_TOPIC_THRESHOLD: float = 0.4
+_SUGGESTION_TEXT: str = (
+    "KB-first — last response had no citation on ArkaOS topic. "
+    "Use @[[note-name]], /kb search, or mcp__obsidian__search_notes "
+    "to ground the next answer."
+)
+
+
+# ─── Result ─────────────────────────────────────────────────────────────
+
+
+@dataclass(frozen=True)
+class CitationResult:
+    """Verdict of a citation check. Immutable; safe to log as JSON."""
+    passed: bool
+    reason: str
+    suggestion: str | None
+    citation_count: int
+    topic_score: float
+
+
+# ─── Public API ─────────────────────────────────────────────────────────
+
+
+def check_citation(
+    response_text: str,
+    *,
+    topic_keywords: frozenset[str] | None = None,
+    bypass_markers: tuple[str, ...] = _BYPASS_DEFAULTS,
+) -> CitationResult:
+    """Classify an assistant response for KB citation discipline."""
+    text = response_text or ""
+    citation_count = _count_citations(text)
+    topic_score = _compute_topic_score(text, topic_keywords or _ARKAOS_KEYWORDS)
+
+    if _has_bypass_marker(text, bypass_markers):
+        return CitationResult(True, "trivial", None, citation_count, topic_score)
+
+    if _is_trivial_length(text):
+        return CitationResult(True, "trivial", None, citation_count, topic_score)
+
+    if citation_count > 0:
+        return CitationResult(True, "cited", None, citation_count, topic_score)
+
+    if topic_score < _TOPIC_THRESHOLD:
+        return CitationResult(True, "off-topic", None, 0, topic_score)
+
+    return CitationResult(False, "missing", _SUGGESTION_TEXT, 0, topic_score)
+
+
+# ─── Helpers (private) ──────────────────────────────────────────────────
+
+
+def _has_bypass_marker(text: str, markers: tuple[str, ...]) -> bool:
+    return any(marker in text for marker in markers)
+
+
+def _is_trivial_length(text: str) -> bool:
+    return len(text.split()) < _TRIVIAL_WORD_THRESHOLD
+
+
+def _count_citations(text: str) -> int:
+    # Truncate to _MAX_SCAN_CHARS first; the file-line regex is the only
+    # backtracking-prone pattern and the bounded quantifiers (capped at 8
+    # segments × 64 chars each) combined with this slice make all three
+    # patterns safe to run unconditionally below.
+    scan = text if len(text) <= _MAX_SCAN_CHARS else text[:_MAX_SCAN_CHARS]
+    wikilinks = len(_WIKILINK_PATTERN.findall(scan))
+    knowledge = 1 if _KNOWLEDGE_PATTERN.search(scan) else 0
+    files = len(_FILE_LINE_PATTERN.findall(scan))
+    return wikilinks + knowledge + files
+
+
+def _compute_topic_score(text: str, keywords: frozenset[str]) -> float:
+    if not keywords:
+        return 0.0
+    lower = text.lower()
+    hits = sum(1 for k in keywords if k.lower() in lower)
+    denom = max(1, len(keywords) // 10)
+    return min(1.0, hits / denom)

package/core/governance/learning_detector.py

@@ -0,0 +1,221 @@
+"""Correction-signal detector for ArkaOS hybrid learning (PR16 v2.38.0).
+
+Implements the `hybrid-learning` NON-NEGOTIABLE rule from PR10
+constitution. The detector scans a user message for signs that the user
+is establishing a permanent rule (rather than a one-off comment), and
+classifies the signal so the orchestrator can:
+
+  * IMPLICIT  — low-leverage correction, auto-save with low confidence
+  * EXPLICIT  — high-leverage correction, surface Marta confirmation
+                question before saving
+
+The detector is heuristic (regex + magnitude). It never writes memory
+files itself — it only emits a structured verdict the Stop hook records
+and the orchestrator acts upon.
+
+Conclave 2026-05-13 brainstorm rule:
+  * Implicit auto-detect with confidence scoring (default)
+  * Explicit Marta-led confirmation for high-leverage rules
+  * Marta is the owner of the learning loop
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import asdict, dataclass, field
+from typing import Literal
+
+CorrectionMode = Literal["explicit", "implicit", "none"]
+CorrectionKind = Literal["rule", "preference", "one-off", "none"]
+
+# Absolute-language cues — strong signal that user is asserting a rule.
+_ABSOLUTE_CUES: tuple[re.Pattern, ...] = tuple(
+    re.compile(p, re.IGNORECASE) for p in [
+        r"\bsempre\b",
+        r"\bnunca\b",
+        r"\btodas?\s+as?\s+vezes\b",
+        r"\bem\s+todos?\s+os?\s+casos\b",
+        r"\bsem\s+exce[cç][oõ]es\b",
+        r"\bno\s+exceptions\b",
+        r"\balways\b",
+        r"\bnever\b",
+        r"\bevery\s+time\b",
+        r"\bin\s+all\s+cases\b",
+        r"\bNON-NEGOTIABLE\b",
+        r"\bn[aã]o[\s-]+negoci[aá]vel\b",
+        r"\bmandatory\b",
+        r"\bobrigat[oó]rio\b",
+        r"\bregra\s+permanente\b",
+        r"\bpermanent\s+rule\b",
+        r"\bguarda\s+isto\b",
+        r"\bsave\s+this\b",
+        r"\bencode\s+this\b",
+        r"\benforce\s+this\b",
+        r"\b(daqui\s+)?para\s+a\s+frente\b",
+        r"\bgoing\s+forward\b",
+    ]
+)
+
+# Correction verbs — "stop doing X" / "I want Y instead".
+_CORRECTION_VERBS: tuple[re.Pattern, ...] = tuple(
+    re.compile(p, re.IGNORECASE) for p in [
+        r"\bn[aã]o\s+(quero|fa[cç]as?|continues?)\b",
+        r"\bp[aá]ra\s+de\b",
+        r"\bdeixa\s+de\b",
+        r"\bevita\b",
+        r"\bstop\s+(doing|saying)\b",
+        r"\bdon[' ]t\s+(do|say|use|assume)\b",
+        r"\bavoid\b",
+        r"\bem\s+vez\s+de\b",
+        r"\binstead\s+of\b",
+        r"\bn[aã]o\s+é\s+(isso|assim)\b",
+        r"\bwrong\b",
+        r"\bnot\s+like\s+that\b",
+    ]
+)
+
+# Self-affirmation cues — "I prefer X" / "what I want is".
+_PREFERENCE_CUES: tuple[re.Pattern, ...] = tuple(
+    re.compile(p, re.IGNORECASE) for p in [
+        r"\b(eu\s+)?prefiro\b",
+        r"\b(eu\s+)?gosto\s+(de|mais)\b",
+        r"\bI\s+prefer\b",
+        r"\bI\s+like\b",
+        r"\bI\s+want\b",
+        r"\bo\s+que\s+(eu\s+)?quero\s+é\b",
+        r"\bwhat\s+I\s+want\s+is\b",
+    ]
+)
+
+# Magnitude thresholds.
+_MIN_CORRECTION_CHARS = 60
+_HIGH_LEVERAGE_CHARS = 200
+
+
+@dataclass
+class CorrectionSignal:
+    """Structured verdict on a potential correction message."""
+
+    mode: CorrectionMode
+    kind: CorrectionKind
+    confidence: float  # 0.0 .. 1.0
+    is_high_leverage: bool
+    signals: list[str] = field(default_factory=list)
+    suggested_memory_type: str = ""  # "feedback" | "preference" | ""
+    message_length: int = 0
+
+    def to_dict(self) -> dict:
+        return asdict(self)
+
+    def should_save(self) -> bool:
+        """Whether the orchestrator should write a memory file."""
+        return self.confidence >= 0.5
+
+    def should_confirm(self) -> bool:
+        """Whether Marta should ask the user to confirm before saving."""
+        return self.is_high_leverage or self.confidence >= 0.85
+
+
+def detect_correction_signal(text: str) -> CorrectionSignal:
+    """Inspect *text* and return a CorrectionSignal verdict.
+
+    Confidence scale (cumulative across signal types, capped at 1.0):
+      0.0   no signal
+      0.4   short message with correction verb
+      0.55  absolute-language cue present (sempre/nunca/etc.)
+      0.7   correction verb + absolute-language cue
+      0.85  long message with multiple cue types
+      1.0   explicit "guarda isto / save this / encode this"
+    """
+    stripped = (text or "").strip()
+    if not stripped:
+        return CorrectionSignal(
+            mode="none", kind="none", confidence=0.0, is_high_leverage=False
+        )
+
+    signals: list[str] = []
+    confidence = 0.0
+    kind: CorrectionKind = "none"
+
+    # Absolute-language cues (strong rule signal).
+    abs_hits = [p.pattern for p in _ABSOLUTE_CUES if p.search(stripped)]
+    if abs_hits:
+        signals.append("absolute-language")
+        confidence = max(confidence, 0.55)
+        kind = "rule"
+
+    # Correction verbs.
+    correction_hits = [p.pattern for p in _CORRECTION_VERBS if p.search(stripped)]
+    if correction_hits:
+        signals.append("correction-verb")
+        confidence = max(confidence, 0.4)
+        if kind == "none":
+            kind = "rule"
+
+    # Preference cues — softer signal, "preference" not "rule".
+    pref_hits = [p.pattern for p in _PREFERENCE_CUES if p.search(stripped)]
+    if pref_hits:
+        signals.append("preference-cue")
+        confidence = max(confidence, 0.35)
+        if kind == "none":
+            kind = "preference"
+
+    # Combination boosts confidence.
+    if abs_hits and correction_hits:
+        signals.append("rule-plus-correction-combo")
+        confidence = max(confidence, 0.7)
+
+    # Explicit save-this verbs are 1.0.
+    save_now = re.search(
+        r"\b(guarda\s+isto|save\s+this|encode\s+this|enforce\s+this|"
+        r"regra\s+permanente|permanent\s+rule|going\s+forward)\b",
+        stripped, re.IGNORECASE,
+    )
+    if save_now:
+        signals.append("explicit-save-verb")
+        confidence = 1.0
+        kind = "rule"
+
+    # Magnitude boost — long substantive corrections are more likely rules.
+    msg_len = len(stripped)
+    is_high_leverage = False
+    if msg_len >= _HIGH_LEVERAGE_CHARS and (abs_hits or correction_hits):
+        signals.append("high-magnitude")
+        confidence = max(confidence, 0.85)
+        is_high_leverage = True
+
+    if msg_len < _MIN_CORRECTION_CHARS and not save_now and not abs_hits:
+        # Too short to be a substantive rule, unless it explicitly says "save"
+        # OR contains an absolute-language cue (e.g. "always", "never",
+        # "NON-NEGOTIABLE"). Those are intentional declarative rules even
+        # when phrased compactly — capping their confidence would silence
+        # the user's clear intent.
+        confidence = min(confidence, 0.4)
+
+    # NON-NEGOTIABLE keyword always escalates to high-leverage.
+    if re.search(r"\bNON-NEGOTIABLE\b|\bn[aã]o[\s-]+negoci[aá]vel\b", stripped, re.IGNORECASE):
+        is_high_leverage = True
+
+    # Mode selection.
+    if confidence < 0.35:
+        mode: CorrectionMode = "none"
+    elif is_high_leverage or confidence >= 0.85:
+        mode = "explicit"
+    else:
+        mode = "implicit"
+
+    suggested = ""
+    if kind == "rule" and confidence >= 0.5:
+        suggested = "feedback"
+    elif kind == "preference" and confidence >= 0.35:
+        suggested = "preference"
+
+    return CorrectionSignal(
+        mode=mode,
+        kind=kind,
+        confidence=round(confidence, 2),
+        is_high_leverage=is_high_leverage,
+        signals=signals,
+        suggested_memory_type=suggested,
+        message_length=msg_len,
+    )