arkaos 4.10.0 → 4.12.0

package/core/evals/sanitizer.py

@@ -0,0 +1,97 @@
+"""Client-identifier sanitizer — distillation prerequisite (evals ADR).
+
+Redacts every client identifier from transcript text BEFORE it can feed
+a LoRA training run. Confidentiality is NON-NEGOTIABLE (v2.18.0 npm
+leak precedent), so this module fails CLOSED: with no redaction config
+on disk there is nothing to prove the text is clean, and sanitize()
+refuses to run rather than pass text through unredacted.
+
+The identifier list is the same one the release leak-scanner uses
+(``~/.arkaos/redaction-clients.json`` via
+``core.governance.leak_scanner.load_redaction_patterns``) — one source
+of truth, never hardcoded in the repo.
+
+Replacement is deterministic: the Nth pattern in the config maps to
+``[CLIENT-N]`` in every run. Corpora stay diffable under the APPEND-ONLY
+invariant — new clients go at the END of the config list; reordering or
+deleting entries remaps the placeholders of everything sanitized before.
+"""
+
+from __future__ import annotations
+
+import re
+import sys
+from pathlib import Path
+
+from core.governance.leak_scanner import load_redaction_patterns
+
+
+class SanitizerConfigMissing(RuntimeError):
+    """No redaction config — sanitization cannot be proven, so it refuses."""
+
+
+def sanitize_text(
+    text: str, config_path: Path | None = None
+) -> tuple[str, dict[str, int]]:
+    """Redact client identifiers; return (clean_text, per-placeholder counts).
+
+    Raises SanitizerConfigMissing when the redaction config is absent or
+    empty — fail closed, never pass text through unproven.
+    """
+    patterns = load_redaction_patterns(config_path)
+    if not patterns:
+        raise SanitizerConfigMissing(
+            "redaction config missing or empty (~/.arkaos/redaction-"
+            "clients.json) — refusing to sanitize without an identifier "
+            "list; a silent pass-through would poison the training corpus"
+        )
+    # SINGLE pass over ONE longest-first alternation (QG blocker,
+    # 2026-07-09): a positional per-pattern loop leaked the suffix of a
+    # longer identifier whenever a shorter prefix pattern came first in
+    # the config ("data" before "data dynamics corp"), and replacement
+    # text could itself be re-matched. Placeholder numbers stay keyed to
+    # CONFIG position, so appends never remap an existing corpus.
+    index_by_pattern = {p: i for i, p in enumerate(patterns, start=1)}
+    alternation = "|".join(
+        re.escape(p) for p in sorted(patterns, key=len, reverse=True)
+    )
+    regex = re.compile(
+        r"(?<![a-z0-9])(" + alternation + r")(?![a-z0-9])", re.IGNORECASE
+    )
+    counts: dict[str, int] = {}
+
+    def _redact(match: re.Match[str]) -> str:
+        placeholder = f"[CLIENT-{index_by_pattern[match.group(1).lower()]}]"
+        counts[placeholder] = counts.get(placeholder, 0) + 1
+        return placeholder
+
+    return regex.sub(_redact, text), counts
+
+
+def sanitize_file(
+    path: Path, config_path: Path | None = None
+) -> tuple[str, dict[str, int]]:
+    return sanitize_text(
+        path.read_text(encoding="utf-8"), config_path=config_path
+    )
+
+
+def main(argv: list[str] | None = None) -> int:
+    """CLI: sanitize a file (or stdin) to stdout; counts on stderr."""
+    args = argv if argv is not None else sys.argv[1:]
+    try:
+        if args:
+            clean, counts = sanitize_file(Path(args[0]))
+        else:
+            clean, counts = sanitize_text(sys.stdin.read())
+    except SanitizerConfigMissing as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 2
+    sys.stdout.write(clean)
+    total = sum(counts.values())
+    print(f"sanitized: {total} redaction(s) {counts}", file=sys.stderr)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/core/evals/verdict_labels.py

@@ -1,14 +1,16 @@
-"""QG verdicts as free eval labels.
-
-Every Quality Gate review already produces a structured ``QGVerdict``
-(APPROVED/REJECTED + blockers + evidence summary). Persisting them turns
-each review into a labeled example — the training/eval signal the E2E
-audit called "labels gratuitos". Append-only JSONL, same conventions as
-the other ``~/.arkaos/telemetry`` writers: never raises, fcntl advisory
-lock via ``llm_cost_telemetry._locked_append`` (QG reviews run as
-parallel subagents and verdict lines far exceed atomic-write sizes, so
-unlocked appends could interleave and corrupt the label corpus),
-``ARKA_QG_LABELS_PATH`` override for tests.
+"""QG and gate-judge verdicts as free eval labels.
+
+Every Quality Gate review produces a structured ``QGVerdict`` and every
+gate judge (Interaction Reform PR2) a ``JudgeVerdict``. Persisting them
+turns each review into a labeled example — the training/eval signal the
+E2E audit called "labels gratuitos". Two corpora, one module:
+``qg-verdicts.jsonl`` and ``judge-verdicts.jsonl``. Append-only JSONL,
+same conventions as the other ``~/.arkaos/telemetry`` writers: never
+raises, fcntl advisory lock via ``llm_cost_telemetry._locked_append``
+(reviews run as parallel subagents and verdict lines far exceed
+atomic-write sizes, so unlocked appends could interleave and corrupt
+the corpus), ``ARKA_QG_LABELS_PATH`` / ``ARKA_JUDGE_LABELS_PATH``
+overrides for tests.
 """
 
 from __future__ import annotations
@@ -19,12 +21,16 @@ from datetime import datetime, timezone
 from pathlib import Path
 from typing import Any
 
+from core.governance.judge import JudgeVerdict
 from core.governance.qg_verdict import QGVerdict
 from core.runtime.llm_cost_telemetry import _locked_append
 
 DEFAULT_LABELS_PATH = (
     Path.home() / ".arkaos" / "telemetry" / "qg-verdicts.jsonl"
 )
+DEFAULT_JUDGE_LABELS_PATH = (
+    Path.home() / ".arkaos" / "telemetry" / "judge-verdicts.jsonl"
+)
 
 
 def _labels_path() -> Path:
@@ -32,6 +38,11 @@ def _labels_path() -> Path:
     return Path(override) if override else DEFAULT_LABELS_PATH
 
 
+def _judge_labels_path() -> Path:
+    override = os.environ.get("ARKA_JUDGE_LABELS_PATH", "").strip()
+    return Path(override) if override else DEFAULT_JUDGE_LABELS_PATH
+
+
 def record_verdict_label(
     verdict: QGVerdict,
     deliverable: str = "",
@@ -55,9 +66,38 @@ def record_verdict_label(
         return
 
 
+def record_judge_label(
+    verdict: JudgeVerdict,
+    deliverable: str = "",
+    department: str = "",
+    session_id: str = "",
+) -> None:
+    """Append one labeled gate-judge example. Never raises."""
+    try:
+        entry: dict[str, Any] = {
+            "ts": datetime.now(timezone.utc).isoformat(),
+            "deliverable": str(deliverable or ""),
+            "department": str(department or ""),
+            "session_id": str(session_id or ""),
+            **verdict.model_dump(),
+        }
+        with _locked_append(_judge_labels_path()) as fh:
+            fh.write(json.dumps(entry, ensure_ascii=False) + "\n")
+    except Exception:  # noqa: BLE001 — telemetry must never raise
+        return
+
+
 def load_verdict_labels(path: Path | None = None) -> list[dict[str, Any]]:
-    """Read all labeled examples; malformed lines are skipped."""
-    target = path or _labels_path()
+    """Read all labeled QG examples; malformed lines are skipped."""
+    return _load_jsonl(path or _labels_path())
+
+
+def load_judge_labels(path: Path | None = None) -> list[dict[str, Any]]:
+    """Read all labeled gate-judge examples; malformed lines are skipped."""
+    return _load_jsonl(path or _judge_labels_path())
+
+
+def _load_jsonl(target: Path) -> list[dict[str, Any]]:
     if not target.exists():
         return []
     out: list[dict[str, Any]] = []

package/core/forge/complexity.py

@@ -107,6 +107,15 @@ def _score_ambiguity(prompt: str, files: list[str]) -> int:
     return max(0, min(100, score))
 
 
+def score_prompt_ambiguity(prompt: str, files: list[str] | None = None) -> int:
+    """Public 0-100 vagueness score for a user prompt.
+
+    Consumed by the UserPromptSubmit hook to suggest `/arka refine`
+    (Interaction Reform PR5) — regex-only, no I/O, hook-budget safe.
+    """
+    return _score_ambiguity(prompt or "", files or [])
+
+
 def _score_risk(prompt: str, files: list[str]) -> int:
     score = 20
     risk_matches = len(_RISK_KEYWORDS.findall(prompt))

package/core/governance/evidence_checks.py

@@ -278,32 +278,88 @@ def _check_coverage(
     return _skip("coverage", "no coverage.xml or junit.xml on disk")
 
 
+def _grep_lines(path: Path, lines: list[str]) -> list[str]:
+    hits = []
+    for lineno_or_text in lines:
+        for name, pattern in _SECURITY_PATTERNS:
+            if pattern.search(lineno_or_text):
+                hits.append(f"{path} [{name}]: {lineno_or_text.strip()[:120]}")
+    return hits
+
+
 def _grep_file(path: Path) -> list[str]:
     try:
-        lines = path.read_text(encoding="utf-8", errors="ignore").splitlines()
+        text = path.read_text(encoding="utf-8", errors="ignore")
     except OSError:
         return []
     hits = []
-    for lineno, line in enumerate(lines, start=1):
+    for lineno, line in enumerate(text.splitlines(), start=1):
         for name, pattern in _SECURITY_PATTERNS:
             if pattern.search(line):
                 hits.append(f"{path}:{lineno} [{name}]")
     return hits
 
 
+def _diff_base(project_dir: Path) -> str | None:
+    """Merge-base with the default branch, or None outside a usable repo."""
+    for ref in ("origin/master", "master", "origin/main", "main"):
+        proc = subprocess.run(
+            ["git", "merge-base", "HEAD", ref],
+            cwd=project_dir, capture_output=True, text=True, timeout=10,
+        )
+        if proc.returncode == 0 and proc.stdout.strip():
+            return proc.stdout.strip()
+    return None
+
+
+def _added_lines(project_dir: Path, base: str, name: str) -> list[str] | None:
+    """Lines ADDED by this change (committed + working tree) vs base.
+
+    Returns None when git cannot answer — callers fall back to the
+    whole-file scan rather than silently passing.
+    """
+    proc = subprocess.run(
+        ["git", "diff", "-U0", base, "--", name],
+        cwd=project_dir, capture_output=True, text=True, timeout=30,
+    )
+    if proc.returncode != 0:
+        return None
+    return [
+        line[1:]
+        for line in proc.stdout.splitlines()
+        if line.startswith("+") and not line.startswith("+++")
+    ]
+
+
 def _check_security_grep(
     project_dir: Path, changed: list[str] | None,
     test_command: str | None, timeout: int,
 ) -> CheckResult:
+    """Diff-aware security sweep over the changed files.
+
+    Scans only lines ADDED relative to the default-branch merge-base —
+    a pre-existing pattern elsewhere in a touched file is master's
+    debt, not this change's (QG blocker, PR1 Interaction Reform:
+    whole-file scans failed changed files on benign pre-existing
+    lines). Falls back to the whole-file scan when git cannot provide
+    a diff (outside a repo, new file, missing base).
+    """
     if not changed:
         return _skip("security-grep", "no changed files provided")
+    base = _diff_base(project_dir)
     hits: list[str] = []
+    mode = "added-lines" if base else "whole-file"
     for name in changed:
         path = Path(name)
         if not path.is_absolute():
             path = project_dir / name
-        if path.is_file():
+        if not path.is_file():
+            continue
+        added = _added_lines(project_dir, base, name) if base else None
+        if added is None:
             hits.extend(_grep_file(path))
+        else:
+            hits.extend(_grep_lines(path, added))
     summary = (
         "no security patterns matched"
         if not hits
@@ -311,7 +367,7 @@ def _check_security_grep(
     )
     return CheckResult(
         check="security-grep", ran=True, passed=not hits,
-        command=f"security-grep over {len(changed)} changed file(s)",
+        command=f"security-grep ({mode}) over {len(changed)} changed file(s)",
         exit_code=None, summary=_tail(summary),
     )
 

package/core/governance/judge.py

@@ -0,0 +1,95 @@
+"""Unified gate-judge schema (Interaction Reform PR2).
+
+``JudgeVerdict`` is the contract every gate judge returns: the
+plan-judge at Gate 2 (judges the planning summary BEFORE it is shown to
+the user) and the output-judge at Gate 4 (judges the deliverable BEFORE
+the Quality Gate personas). Judges close the fragmentation gap — the
+Forge critic only judged plans inside Forge runs, adversarial-review
+only judged dev diffs, and Gate 4's excellence check was prose
+instruction with no structured output.
+
+Like ``qg_verdict.QGVerdict``, this module is schema + validation only:
+the runtime never invokes models from Python. The orchestrator
+dispatches the judge via the Agent tool with
+``JUDGE_VERDICT_JSON_SCHEMA`` as the structured-output schema (see
+``arka/skills/flow/SKILL.md`` Gates 2 and 4) and records the verdict via
+``core.evals.record_cli --kind judge``.
+
+The judge applies the ``arkaos-not-yes-man`` standard in BOTH
+directions: findings judge the AGENT's work adversarially, and
+``user_challenge`` carries the pushback when the USER's request itself
+is technically wrong — the orchestrator must surface it, never swallow
+it.
+"""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import BaseModel, Field, model_validator
+
+
+class JudgeFinding(BaseModel):
+    """One concrete defect or risk the judge found."""
+
+    area: str = Field(
+        description=(
+            "Rubric area: scope, verification, assumptions, excellence, "
+            "consistency, risk…"
+        )
+    )
+    detail: str = Field(description="What exactly is wrong, with evidence")
+    severity: Literal["blocker", "major", "minor"]
+    verdict: Literal["CONFIRMED", "PLAUSIBLE", "REFUTED"] | None = Field(
+        default=None,
+        description=(
+            "Claim-level verdict after attempting reproduction; REFUTED is "
+            "recorded for telemetry and must NOT count toward REVISE"
+        ),
+    )
+
+
+class JudgeVerdict(BaseModel):
+    """Binary gate-judge verdict. REVISE loops the work, max 2 times."""
+
+    gate: Literal["G2", "G4"]
+    role: Literal["plan-judge", "output-judge"]
+    verdict: Literal["PASS", "REVISE"]
+    findings: list[JudgeFinding] = Field(default_factory=list)
+    user_challenge: str = Field(
+        default="",
+        description=(
+            "Non-empty when the USER's request is technically wrong or "
+            "would ship a worse product — the orchestrator presents this "
+            "alongside the plan (pushback protocol, arkaos-not-yes-man)"
+        ),
+    )
+    judged_digest: str = Field(
+        default="",
+        max_length=120,
+        description="Opening excerpt of the judged artifact (auditability)",
+    )
+    reviewer: str = Field(description="Judge id, e.g. plan-judge-g2")
+    model_used: str = Field(description="Model tier the judgment ran on")
+    notes: str = ""
+
+    @model_validator(mode="after")
+    def revise_requires_actionable_findings(self) -> "JudgeVerdict":
+        """REVISE must cite at least one blocker/major finding —
+        a judge cannot loop work back on narrative alone."""
+        if self.verdict == "REVISE":
+            actionable = [
+                f
+                for f in self.findings
+                if f.severity in ("blocker", "major") and f.verdict != "REFUTED"
+            ]
+            if not actionable:
+                raise ValueError(
+                    "REVISE verdict without an actionable (blocker/major, "
+                    "non-REFUTED) finding — judges loop work on evidence, "
+                    "never on narrative"
+                )
+        return self
+
+
+JUDGE_VERDICT_JSON_SCHEMA: dict = JudgeVerdict.model_json_schema()

package/core/governance/leak_scanner.py

@@ -93,6 +93,16 @@ def scan_text(
     return [m.group(1).lower() for m in regex.finditer(text)]
 
 
+def load_redaction_patterns(config_path: Path | None = None) -> tuple[str, ...]:
+    """Public accessor for the redaction client list.
+
+    Consumed by core.evals.sanitizer (distillation prerequisite) so the
+    scanner and the sanitizer can never disagree on what a client
+    identifier is. Returns () when the config is missing or empty.
+    """
+    return _load_patterns(config_path or _DEFAULT_CONFIG_PATH)
+
+
 def _load_patterns(config_path: Path) -> tuple[str, ...]:
     try:
         data = json.loads(config_path.read_text(encoding="utf-8"))

package/core/governance/phantom_action_check.py

@@ -45,7 +45,12 @@ _ANALYTIC_NOUN = (
     r"|takeaways?|impressions?|sense|grasp|view|idea|picture"
     r"|mental\s+model|contexto|resumo|notas?|entendimento"
     r"|perce[çc][ãa]o|an[áa]lise|analysis|ideia|vis[ãa]o|imagem"
-    r"|no[çc][ãa]o|perspe[ct]?tiva|opini[ãa]o|conhecimento|knowledge)\b"
+    r"|no[çc][ãa]o|perspe[ct]?tiva|opini[ãa]o|conhecimento|knowledge"
+    # Synonym tail (ADR 2026-07-09-phantom M3): noun-reads anchored by
+    # the preposition — plurals included — so verb uses ("read the
+    # file") stay untouched.
+    r"|read(?:ing)?s?(?=\s+(?:on|of)\b)|takes?(?=\s+on\b)"
+    r"|interpretations?|assessments?|interpreta[çc][õã][eo]s?|leituras?)\b"
 )
 _GAP = r"(?:(?!" + _ANALYTIC_NOUN + r")[^.\n!?]){0,60}?"
 
@@ -67,7 +72,17 @@ _BOUND_PT = (
     r"|movi|apliquei|corri|executei)\b" + _GAP + _EFFECT_OBJECT
 )
 _BOUND_EN = (
-    r"\bI(?:'ve| have)?\s+(?:just\s+)?(created|wrote|updated|deleted"
+    # Optional coordinated clause after the I-subject (ADR 2026-07-09-
+    # phantom M2): "I ran through the plan, then ran the tests" — the
+    # second bare verb shares the subject. The chunk must START with the
+    # I-clause's own idiom verb (ran into/through/over/across), so an
+    # embedded clause with a third-party subject ("I confirmed the hook
+    # ran and created…") can never bridge the I anchor to a foreign
+    # effect verb (QG blocker, 2026-07-09 re-review).
+    r"\bI(?:'ve| have)?\s+(?:just\s+)?"
+    r"(?:ran\s+(?:into|through|over|across)\b"
+    r"[^.\n!?]{0,40}?[,;]?\s*\b(?:then|and)\s+)?"
+    r"(created|wrote|updated|deleted"
     r"|added|moved|applied|renamed|ran(?!\s+(?:into|through|over|across))"
     r"|executed)\b" + _GAP + _EFFECT_OBJECT
 )
@@ -135,6 +150,47 @@ def count_turn_tool_uses(raw_transcript: str | None) -> int | None:
     return count
 
 
+def current_turn_assistant_texts(raw_transcript: str | None) -> list[str] | None:
+    """Assistant message texts of the CURRENT turn (after the last real
+    user message). None when the transcript is unparseable or no real
+    user message is found — callers must fail open on None.
+
+    Shares the turn-boundary logic with ``count_turn_tool_uses`` so
+    turn-scoped consumers (plan-approval's mark_presented) do not span
+    turns and re-trigger on a prior turn's markers.
+    """
+    if not raw_transcript:
+        return None
+    records = _parse_jsonl(raw_transcript)
+    if not records:
+        return None
+    start = _last_real_user_index(records)
+    if start < 0:
+        return None
+    texts: list[str] = []
+    for record in records[start + 1 :]:
+        if _record_role(record) != "assistant":
+            continue
+        text = _assistant_text(_record_content(record))
+        if text:
+            texts.append(text)
+    return texts
+
+
+def _assistant_text(content: object) -> str:
+    """Flatten an assistant record's content to its text blocks."""
+    if isinstance(content, str):
+        return content
+    if isinstance(content, list):
+        parts = [
+            block.get("text", "")
+            for block in content
+            if isinstance(block, dict) and block.get("type") == "text"
+        ]
+        return "\n".join(p for p in parts if p)
+    return ""
+
+
 def check_phantom_actions(
     response_text: str, raw_transcript: str | None
 ) -> PhantomActionResult:

package/core/hooks/post_tool_use.py

@@ -642,6 +642,19 @@ def main(stdin_json: dict | None = None) -> int:
     except Exception:  # noqa: BLE001 — telemetry must never break the hook
         pass
 
+    # Interaction Reform PR3 — the native plan-mode approve button IS
+    # explicit plan approval: a successful ExitPlanMode marks the
+    # session approved (stronger, less ambiguous than a text "sim").
+    if tool_name == "ExitPlanMode" and exit_code in ("0", ""):
+        try:
+            from core.workflow import plan_approval
+            if session_id:
+                plan_approval.mark_approved(
+                    session_id, source="exit-plan-mode"
+                )
+        except Exception:  # noqa: BLE001 — hooks never break the turn
+            pass
+
     if tool_name in ("Task", "Agent"):
         subagent_type = get_str(stdin_json, "tool_input", "subagent_type")
         if subagent_type == "cqo":

package/core/hooks/stop.py

@@ -149,6 +149,29 @@ def _flow_checks(
     except Exception:
         pass
 
+    # Interaction Reform PR3 — a turn whose furthest gate is Gate 2 means
+    # a plan is on the table awaiting the user; record it so the next
+    # user message can be classified as approval (plan_approval state).
+    # Scope to the CURRENT turn's messages (QG 2026-07-09, PR4
+    # prerequisite #1, re-review): scanning the whole 20-message window
+    # would re-trigger on a PRIOR turn's [arka:gate:2] still in the
+    # window and silently invalidate a live approval. Turn-scoping keeps
+    # the mid-turn fix (gate:2 + a separate marker-less summary in the
+    # same turn) while never spanning turns. Falls back to the last
+    # message only when the transcript can't be turn-parsed.
+    try:
+        from core.governance.phantom_action_check import (
+            current_turn_assistant_texts,
+        )
+        from core.workflow.gate_checkpoint import extract_latest_gate
+        from core.workflow import plan_approval
+        turn = current_turn_assistant_texts(raw)
+        scan = turn if turn is not None else [last]
+        if session_id and extract_latest_gate(scan) == 2:
+            plan_approval.mark_presented(session_id)
+    except Exception:
+        pass
+
     meta_tag_found = bool(re.search(r"\[arka:meta\]", last, re.IGNORECASE))
 
     sycophancy_signals: list = []