arkaos 4.11.0 → 4.12.0

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/phantom_action_check.py

@@ -150,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 = []

package/core/hooks/user_prompt_submit.py

@@ -102,6 +102,26 @@ _VAGUE_PHRASES = (
     "esse ficheiro", "esse erro", "aquele bug",
 )
 
+# A prompt is CONCRETE (never refine-worthy) when it names a real
+# target: a file (foo.py, README.md, path/to/x), a CamelCase or
+# snake_case code identifier (AuthService, user_repo), or a backticked
+# term. Kills the "no files → +20 constant" false positives the scorer
+# alone can't distinguish (QG 2026-07-09).
+# NOTE: NOT case-insensitive — the CamelCase alternation depends on real
+# case (IGNORECASE would match any two-syllable lowercase word like
+# "melhor" and defeat the whole carve-out).
+_CONCRETE_TARGET_RE = re.compile(
+    r"[\w./-]+\.[A-Za-z]{1,5}\b"        # file with a real extension
+    r"|[\w-]+/[\w./-]+"                 # path segments (a/b/c)
+    r"|\b[A-Z][a-z0-9]+[A-Z]\w+\b"      # CamelCase identifier
+    r"|\b[a-z]+_[a-z0-9_]+\b"           # snake_case identifier
+    r"|`[^`]+`"                         # backticked term
+)
+
+
+def _names_concrete_target(text: str) -> bool:
+    return bool(_CONCRETE_TARGET_RE.search(text or ""))
+
 
 # ─── Sections 1-2: migration + sync detection ────────────────────────────
 
@@ -573,9 +593,56 @@ def main(stdin_json: dict | None = None, raw: str = "") -> int:
     )
 
     workflow_directive = ""
+    refine_hint = ""
     if user_input and _wf_classify(user_input):
         _wf_mark_required(session_id)
         workflow_directive = _WORKFLOW_DIRECTIVE
+        # Interaction Reform PR5 — a vague code-modifying request is a
+        # signal to refine the prompt (ask about the topic) BEFORE the
+        # workflow. SUGGESTION only; /do decides. Not a slash command.
+        # Calibration (QG 2026-07-09): the scorer's +20 "no files" branch
+        # is a constant in the hook context (the hook never has files), so
+        # 70 is the floor for ANY short prompt. Two guards keep clear asks
+        # out — a higher threshold (85, above that constant) AND a
+        # concrete-target carve-out: a prompt that names a file or a code
+        # identifier ("fix the typo in README.md", "add a test to
+        # AuthService") is specific, never refine-worthy.
+        if (
+            not user_input.strip().startswith("/")
+            and not _names_concrete_target(user_input)
+        ):
+            try:
+                from core.forge.complexity import score_prompt_ambiguity
+                score = score_prompt_ambiguity(user_input)
+                if score >= 85:
+                    refine_hint = (
+                        f"[arka:refine-suggested] score={score}/100 — the "
+                        f"request may be vague; consider /arka refine to ask "
+                        f"about the topic and compile a precise prompt "
+                        f"before building."
+                    )
+            except Exception:
+                pass
+
+    # Interaction Reform PR3 — when the previous turn ended at Gate 2
+    # (plan on the table), classify THIS message as approval/rejection.
+    # UserPromptSubmit runs before the turn's tool calls, so the token
+    # is visible to the PreToolUse enforcer with no marker-invisibility
+    # problem. Never blocks the hook.
+    try:
+        from core.workflow import plan_approval
+        if session_id and user_input and plan_approval.is_presented(session_id):
+            verdict = plan_approval.classify_reply(
+                user_input, has_creation_verb=_wf_classify(user_input)
+            )
+            if verdict == "approve":
+                plan_approval.mark_approved(
+                    session_id, source="text", excerpt=user_input
+                )
+            elif verdict == "reject":
+                plan_approval.mark_rejected(session_id)
+    except Exception:
+        pass
 
     context_hits = _cognitive_hits(session_id)
 
@@ -591,6 +658,8 @@ def main(stdin_json: dict | None = None, raw: str = "") -> int:
     )
     if hygiene:
         out = f"{out} {hygiene}"
+    if refine_hint:
+        out = f"{out}\n{refine_hint}"
     for nudge in (kb_cite_nudge, meta_tag_nudge, closing_marker_nudge):
         if nudge:
             out = f"{out}\n{nudge}"

package/core/knowledge/recipes.py

@@ -0,0 +1,237 @@
+"""Validated feature recipes (Interaction Reform PR7).
+
+A Recipe is the missing artifact between the Pattern Library (short text
+hints) and scaffold (whole generic starter repos): a QG-APPROVED feature
+implementation captured with its reference files so the same feature —
+"Laravel login the ArkaOS-approved way" — is reused across projects
+instead of re-derived from documentation every time.
+
+Layout on disk (``~/.arkaos/recipes/<slug>/``):
+    recipe.json   # structured metadata (source of truth for retrieval)
+    RECIPE.md     # narrative: problem, approach, decisions, how to apply
+    files/        # SANITIZED reference files (exemplary feature code)
+
+Confidentiality is NON-NEGOTIABLE (v2.18.0 npm leak precedent): capture
+runs every text field and every reference file through
+``core.evals.sanitizer.sanitize_text`` BEFORE writing. No redaction
+config → ``SanitizerConfigMissing`` → capture REFUSED. There is no write
+path that skips sanitization, and ``sanitized`` must be True to persist.
+
+Admission: only a verdict of APPROVED with a timestamp that ties back to
+``~/.arkaos/telemetry/qg-verdicts.jsonl`` promotes a deliverable to a
+recipe, and capture is always operator-confirmed (the QG skill proposes
+it; it never fires silently).
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+from pathlib import Path
+from typing import Literal
+
+from pydantic import BaseModel, Field, field_validator
+
+from core.evals.sanitizer import sanitize_text
+from core.governance.leak_scanner import load_redaction_patterns
+from core.shared.safe_session_id import safe_session_id
+
+MAX_FILES = 20
+MAX_TOTAL_BYTES = 200 * 1024
+
+
+def _recipes_root() -> Path:
+    override = os.environ.get("ARKA_RECIPES_DIR", "").strip()
+    return Path(override) if override else Path.home() / ".arkaos" / "recipes"
+
+
+class RecipeProvenance(BaseModel):
+    """Where a recipe came from — all fields already sanitized."""
+
+    source_project: str = Field(description="Origin project ([CLIENT-N] if client)")
+    qg_verdict: Literal["APPROVED"]
+    qg_verdict_ts: str = Field(description="Ties to qg-verdicts.jsonl")
+    captured_at: str
+    department: str = ""
+
+
+class Recipe(BaseModel):
+    """A reusable, QG-approved feature implementation."""
+
+    slug: str
+    name: str
+    problem: str = Field(min_length=10)
+    stack: list[str] = Field(min_length=1)
+    feature_keywords: list[str] = Field(min_length=1)
+    files: list[str] = Field(default_factory=list)
+    acceptance_criteria: list[str] = Field(default_factory=list)
+    apply_notes: str = ""
+    provenance: RecipeProvenance
+    sanitized: bool = False
+
+    @field_validator("slug")
+    @classmethod
+    def _slug_is_path_safe(cls, value: str) -> str:
+        if safe_session_id(value) != value:
+            raise ValueError(
+                f"unsafe recipe slug {value!r} — must be a path-safe token"
+            )
+        return value
+
+    @field_validator("files")
+    @classmethod
+    def _within_file_cap(cls, value: list[str]) -> list[str]:
+        if len(value) > MAX_FILES:
+            raise ValueError(
+                f"recipe has {len(value)} files, cap is {MAX_FILES}"
+            )
+        return value
+
+
+class RecipeCaptureRefused(RuntimeError):
+    """Capture cannot proceed safely (unsanitized, oversize, bad verdict)."""
+
+
+def _recipe_dir(slug: str) -> Path:
+    return _recipes_root() / slug
+
+
+def _redaction_patterns(config_path: Path | None) -> tuple[str, ...]:
+    """Lowercased client patterns for substring filename screening."""
+    return tuple(p.lower() for p in load_redaction_patterns(config_path))
+
+
+def _is_safe_relpath(rel_path: str) -> bool:
+    """Reject absolute paths, '..' escapes, backslashes, and leading dots.
+
+    Reference files live strictly under ``files/`` (CWE-22 guard). They
+    cannot collide with the recipe's own metadata because they are
+    written into the ``files/`` subdirectory, never the recipe root.
+    """
+    if not rel_path or rel_path.startswith(("/", ".")) or "\\" in rel_path:
+        return False
+    if Path(rel_path).is_absolute():
+        return False
+    return all(part not in ("..", "") for part in Path(rel_path).parts)
+
+
+def capture_recipe(
+    recipe: Recipe,
+    narrative: str,
+    reference_files: dict[str, str],
+    config_path: Path | None = None,
+) -> Path:
+    """Sanitize everything, then persist a recipe. Fail-closed.
+
+    ``reference_files`` maps a relative path under ``files/`` to its raw
+    content. Every text field, the narrative, and each file are run
+    through the sanitizer first; ``SanitizerConfigMissing`` propagates
+    (capture refused). Raises ``RecipeCaptureRefused`` on oversize input
+    or a non-APPROVED verdict.
+    """
+    if recipe.provenance.qg_verdict != "APPROVED":
+        raise RecipeCaptureRefused("only APPROVED deliverables become recipes")
+    if len(reference_files) > MAX_FILES:
+        raise RecipeCaptureRefused(
+            f"{len(reference_files)} files exceeds the {MAX_FILES} cap"
+        )
+    total = sum(len(c.encode("utf-8")) for c in reference_files.values())
+    if total > MAX_TOTAL_BYTES:
+        raise RecipeCaptureRefused(
+            f"reference files total {total} B exceeds {MAX_TOTAL_BYTES} B"
+        )
+    def _clean(text: str) -> str:
+        return sanitize_text(text, config_path=config_path)[0]
+
+    patterns = _redaction_patterns(config_path)
+    for rel_path in reference_files:
+        if not _is_safe_relpath(rel_path):
+            raise RecipeCaptureRefused(
+                f"unsafe reference path {rel_path!r} — must stay under files/"
+            )
+        # A filename can carry a client identifier that reaches both
+        # recipe.json and the on-disk path. Filenames are not free text
+        # to rewrite, so REFUSE rather than mangle. The word-bounded
+        # sanitizer misses a name GLUED into a CamelCase filename
+        # (GlobexAuthService.php), so check the redaction patterns as
+        # plain case-insensitive substrings here (confidentiality is
+        # NON-NEGOTIABLE, QG 2026-07-09).
+        lowered = rel_path.lower()
+        if any(p in lowered for p in patterns):
+            raise RecipeCaptureRefused(
+                f"reference filename {rel_path!r} carries a client "
+                f"identifier — rename it before capture"
+            )
+
+    clean_narrative = _clean(narrative)
+    clean_files = {
+        rel_path: _clean(content)
+        for rel_path, content in reference_files.items()
+    }
+
+    # EVERY free-text field that reaches recipe.json must be sanitized.
+    # The model_copy update dict is the single sanitize gate — if a new
+    # free-text field is added to Recipe, add it here or it leaks
+    # (confidentiality is NON-NEGOTIABLE).
+    clean_provenance = recipe.provenance.model_copy(update={
+        "source_project": _clean(recipe.provenance.source_project),
+        "department": _clean(recipe.provenance.department),
+    })
+    stored = recipe.model_copy(update={
+        "name": _clean(recipe.name),
+        "problem": _clean(recipe.problem),
+        "stack": [_clean(s) for s in recipe.stack],
+        "feature_keywords": [_clean(k) for k in recipe.feature_keywords],
+        "acceptance_criteria": [_clean(c) for c in recipe.acceptance_criteria],
+        "apply_notes": _clean(recipe.apply_notes),
+        "files": sorted(clean_files.keys()),
+        "provenance": clean_provenance,
+        "sanitized": True,
+    })
+
+    target = _recipe_dir(stored.slug)
+    (target / "files").mkdir(parents=True, exist_ok=True)
+    (target / "recipe.json").write_text(
+        stored.model_dump_json(indent=2) + "\n", encoding="utf-8"
+    )
+    (target / "RECIPE.md").write_text(clean_narrative + "\n", encoding="utf-8")
+    for rel_path, content in clean_files.items():
+        dest = target / "files" / rel_path
+        dest.parent.mkdir(parents=True, exist_ok=True)
+        dest.write_text(content, encoding="utf-8")
+    return target
+
+
+def load_recipe(slug: str) -> Recipe | None:
+    if safe_session_id(slug) != slug:
+        return None
+    path = _recipe_dir(slug) / "recipe.json"
+    if not path.exists():
+        return None
+    try:
+        return Recipe.model_validate_json(path.read_text(encoding="utf-8"))
+    except Exception:  # noqa: BLE001 — corrupt recipe is simply skipped
+        return None
+
+
+def list_recipes() -> list[Recipe]:
+    root = _recipes_root()
+    if not root.exists():
+        return []
+    out: list[Recipe] = []
+    for entry in sorted(root.iterdir()):
+        if entry.is_dir():
+            recipe = load_recipe(entry.name)
+            if recipe is not None:
+                out.append(recipe)
+    return out
+
+
+def delete_recipe(slug: str) -> bool:
+    if safe_session_id(slug) != slug:
+        return False
+    target = _recipe_dir(slug)
+    if not target.exists():
+        return False
+    shutil.rmtree(target)
+    return True