arkaos 4.11.0 → 4.13.0

package/config/mcp-policy.yaml

@@ -12,6 +12,7 @@ policies:
   - match:
       stack_includes: [laravel, php]
     active:
+      - codebase-memory
       - arka-prompts
       - obsidian
       - context7
@@ -36,12 +37,14 @@ policies:
       - teams
       - shopify-dev
       - mirakl
+      - higgsfield
     ambiguous: []
 
   # --- Frontend: Nuxt / Vue ---
   - match:
       stack_includes: [nuxt, vue]
     active:
+      - codebase-memory
       - arka-prompts
       - obsidian
       - context7
@@ -66,12 +69,14 @@ policies:
       - teams
       - shopify-dev
       - mirakl
+      - higgsfield
     ambiguous: []
 
   # --- Frontend: React / Next ---
   - match:
       stack_includes: [next, react]
     active:
+      - codebase-memory
       - arka-prompts
       - obsidian
       - context7
@@ -96,6 +101,7 @@ policies:
       - teams
       - shopify-dev
       - mirakl
+      - higgsfield
     ambiguous: []
 
   # --- E-commerce (Shopify / Mirakl) ---
@@ -111,6 +117,7 @@ policies:
       - mirakl
       - sentry
     deferred:
+      - codebase-memory
       - memory-bank
       - postgres
       - supabase
@@ -126,12 +133,14 @@ policies:
       - discord
       - whatsapp
       - teams
+      - higgsfield
     ambiguous: []
 
   # --- Python projects ---
   - match:
       stack_includes: [python]
     active:
+      - codebase-memory
       - arka-prompts
       - obsidian
       - context7
@@ -156,6 +165,7 @@ policies:
       - teams
       - shopify-dev
       - mirakl
+      - higgsfield
     ambiguous: []
 
   # --- Ecosystem: marketing ---
@@ -169,6 +179,7 @@ policies:
       - firecrawl
       - clickup
     deferred:
+      - codebase-memory
       - memory-bank
       - gh-grep
       - postgres
@@ -186,6 +197,7 @@ policies:
       - teams
       - shopify-dev
       - mirakl
+      - higgsfield
     ambiguous: []
 
   # --- Ecosystem: content ---
@@ -197,7 +209,9 @@ policies:
       - context7
       - canva
       - firecrawl
+      - higgsfield
     deferred:
+      - codebase-memory
       - memory-bank
       - gh-grep
       - postgres
@@ -227,6 +241,7 @@ policies:
       - context7
       - gh-grep
     deferred:
+      - codebase-memory
       - memory-bank
       - postgres
       - supabase
@@ -246,4 +261,5 @@ policies:
       - teams
       - shopify-dev
       - mirakl
+      - higgsfield
     ambiguous: []

package/config/output-styles/arkaos.md

@@ -0,0 +1,52 @@
+---
+name: ArkaOS
+description: ArkaOS Operating System personality — squad-driven, framework-backed, branded responses
+keep-coding-instructions: true
+---
+
+# ArkaOS Output Style
+
+You are operating as ArkaOS — the Operating System for AI Agent Teams. You orchestrate the ArkaOS specialized agent departments.
+
+## Core Behavior
+
+- Every request routes through the appropriate department squad. Never respond as a generic assistant.
+- Use framework-backed reasoning: cite the framework behind your recommendations (SOLID, StoryBrand, Porter's Five Forces, AARRR, etc.)
+- Apply critical thinking before executing. Ask clarifying questions when intent is ambiguous.
+- Quality Gate mindset: everything you produce should be production-ready, reviewed, and validated.
+
+## Challenge the User
+
+- When the user's request is technically wrong, mathematically impossible,
+  or would ship a worse product, challenge it BEFORE executing — pushback
+  protocol, constitution rule `arkaos-not-yes-man`.
+- Ground the challenge in evidence or a reference company (Stripe, Linear,
+  Vercel, Notion…), never in opinion alone.
+- Insistence is not new evidence: never grow more agreeable under pressure.
+  If the user directs execution anyway, execute under explicit objection,
+  on record.
+- Apply the same standard to agents and subagents: judge their plans and
+  outputs adversarially — delivering fast is worthless when the solution
+  is wrong.
+
+## Response Style
+
+- Be direct and concise. Lead with the action or answer, not preamble.
+- When routing to a department, announce it: "Routing to [Department] — [Lead Agent] coordinating."
+- Use structured output: headers, tables, bullet points. No walls of text.
+- For code: follow SOLID principles, clean code, conventional commits.
+- For content: human-quality writing, no AI cliches, culturally appropriate for the target market.
+
+## Squad Awareness
+
+When handling requests, think in squads:
+- Who is the department lead for this domain?
+- Which specialists should execute?
+- Does this need cross-department collaboration?
+- Does this need Quality Gate review?
+
+## Language
+
+- Match the user's language (Portuguese or English).
+- When writing in Portuguese, use European Portuguese (pt-PT), never Brazilian.
+- Technical terms can stay in English when that's the industry standard.

package/core/evals/__init__.py

@@ -7,13 +7,17 @@ or local-model distillation consumes.
 
 from core.evals.schema import EvalTask, load_eval_tasks
 from core.evals.verdict_labels import (
+    load_judge_labels,
     load_verdict_labels,
+    record_judge_label,
     record_verdict_label,
 )
 
 __all__ = [
     "EvalTask",
     "load_eval_tasks",
+    "load_judge_labels",
     "load_verdict_labels",
+    "record_judge_label",
     "record_verdict_label",
 ]

package/core/evals/record_cli.py

@@ -1,10 +1,11 @@
-"""Record a QGVerdict as an eval label — the QG-skill wiring point.
+"""Record a QGVerdict or gate JudgeVerdict as an eval label.
 
-Reads the reviewer's QGVerdict JSON from stdin (or --file) and appends
-it to the label corpus via ``record_verdict_label``. Invoked by the
-orchestrator right after a Quality Gate verdict lands (see the Quality
-Gate skill instructions), closing the "labels gratuitos" loop from the
-evals ADR.
+Reads the reviewer's verdict JSON from stdin (or --file) and appends it
+to the matching label corpus (``--kind qg`` → qg-verdicts.jsonl,
+``--kind judge`` → judge-verdicts.jsonl). Invoked by the orchestrator
+right after a Quality Gate verdict or a gate-judge verdict lands (see
+the Quality Gate and flow skill instructions), closing the "labels
+gratuitos" loop from the evals ADR.
 
 Unlike the underlying writer (telemetry contract: never raises), this
 explicit CLI fails LOUDLY on invalid verdict JSON — a malformed label
@@ -20,13 +21,20 @@ from pathlib import Path
 
 from pydantic import ValidationError
 
-from core.evals.verdict_labels import record_verdict_label
+from core.evals.verdict_labels import record_judge_label, record_verdict_label
+from core.governance.judge import JudgeVerdict
 from core.governance.qg_verdict import QGVerdict
 
 
 def main(argv: list[str] | None = None) -> int:
     parser = argparse.ArgumentParser(description=__doc__)
     parser.add_argument("--file", help="verdict JSON file (default: stdin)")
+    parser.add_argument(
+        "--kind",
+        choices=("qg", "judge"),
+        default="qg",
+        help="qg = QGVerdict (default); judge = gate JudgeVerdict (PR2)",
+    )
     parser.add_argument("--deliverable", default="")
     parser.add_argument("--department", default="")
     parser.add_argument("--eval-task-id", default="")
@@ -38,12 +46,17 @@ def main(argv: list[str] | None = None) -> int:
         if args.file
         else sys.stdin.read()
     )
+    if args.kind == "judge":
+        return _record_judge(raw, args)
+    return _record_qg(raw, args)
+
+
+def _record_qg(raw: str, args: argparse.Namespace) -> int:
     try:
         verdict = QGVerdict.model_validate(json.loads(raw))
     except (json.JSONDecodeError, ValidationError) as exc:
         print(f"error: invalid QGVerdict JSON — {exc}", file=sys.stderr)
         return 1
-
     record_verdict_label(
         verdict,
         deliverable=args.deliverable,
@@ -59,5 +72,25 @@ def main(argv: list[str] | None = None) -> int:
     return 0
 
 
+def _record_judge(raw: str, args: argparse.Namespace) -> int:
+    try:
+        verdict = JudgeVerdict.model_validate(json.loads(raw))
+    except (json.JSONDecodeError, ValidationError) as exc:
+        print(f"error: invalid JudgeVerdict JSON — {exc}", file=sys.stderr)
+        return 1
+    record_judge_label(
+        verdict,
+        deliverable=args.deliverable,
+        department=args.department,
+        session_id=args.session_id,
+    )
+    print(json.dumps({
+        "recorded": True,
+        "verdict": verdict.verdict,
+        "gate": verdict.gate,
+    }))
+    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

@@ -28,6 +28,7 @@ import re
 import shlex
 import shutil
 import subprocess
+import time
 from dataclasses import asdict, dataclass, field
 from pathlib import Path
 
@@ -37,8 +38,16 @@ TIMEOUT_SECONDS = 300
 COVERAGE_THRESHOLD = 80.0
 ALL_CHECKS: tuple[str, ...] = (
     "lint", "typecheck", "tests", "coverage", "security-grep", "spellcheck",
+    "ui-screenshot",
 )
 
+# ui-screenshot artifact contract (Excellence Reform PR-D3): captures land
+# in <project>/.arka/evidence/ui/ per brand/design-review; the check only
+# stats files (read-only), it never runs a browser.
+UI_EVIDENCE_DIR = Path(".arka") / "evidence" / "ui"
+UI_SCREENSHOT_WINDOW_HOURS = 24
+UI_SCREENSHOT_MIN_BYTES = 10 * 1024
+
 _MAX_SUMMARY_CHARS = 800
 _MAX_GREP_HITS = 20
 
@@ -278,32 +287,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 +376,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),
     )
 
@@ -328,6 +393,66 @@ def _check_spellcheck(
     return _run("spellcheck", ["codespell", *md_files], project_dir, timeout)
 
 
+def _check_ui_screenshot(
+    project_dir: Path, changed: list[str] | None,
+    test_command: str | None, timeout: int,
+) -> CheckResult:
+    """UI-touching changes require a recent screenshot artifact.
+
+    Mechanical half of the visual-review loop (excellence-mandate): a
+    PNG > 10KB captured within the last 24h under
+    ``<project>/.arka/evidence/ui/``. The judgment half — whether the
+    pixels hold up against the benchmark named in the ``[arka:design]``
+    marker — stays with Francisca, who Reads the artifact this check
+    points at. Skips when no UI files changed; read-only (stat only).
+    """
+    if not changed:
+        return _skip("ui-screenshot", "no changed files provided")
+    try:
+        from core.workflow.frontend_gate import is_ui_file
+    except Exception:
+        return _skip("ui-screenshot", "frontend_gate unavailable")
+    ui_changed = [f for f in changed if is_ui_file(f)]
+    if not ui_changed:
+        return _skip("ui-screenshot", "no UI files changed")
+    command_str = (
+        f"scan:{UI_EVIDENCE_DIR} (png >{UI_SCREENSHOT_MIN_BYTES // 1024}KB, "
+        f"last {UI_SCREENSHOT_WINDOW_HOURS}h)"
+    )
+    evidence_dir = project_dir / UI_EVIDENCE_DIR
+    cutoff = time.time() - UI_SCREENSHOT_WINDOW_HOURS * 3600
+    candidates: list[tuple[float, Path]] = []
+    if evidence_dir.is_dir():
+        for png in evidence_dir.rglob("*.png"):
+            try:
+                stat = png.stat()
+            except OSError:
+                continue
+            if stat.st_mtime >= cutoff and stat.st_size > UI_SCREENSHOT_MIN_BYTES:
+                candidates.append((stat.st_mtime, png))
+    if candidates:
+        newest = max(candidates)[1]
+        return CheckResult(
+            check="ui-screenshot", ran=True, passed=True,
+            command=command_str, exit_code=None,
+            summary=(
+                f"{len(candidates)} recent screenshot(s) for "
+                f"{len(ui_changed)} changed UI file(s); newest: {newest.name}"
+            ),
+            details_path=str(newest),
+        )
+    return CheckResult(
+        check="ui-screenshot", ran=True, passed=False,
+        command=command_str, exit_code=None,
+        summary=(
+            f"{len(ui_changed)} UI file(s) changed but no screenshot "
+            f"evidence under {UI_EVIDENCE_DIR}/ — capture per "
+            "brand/design-review (Playwright first, 1440+390 widths) or "
+            "record an explicit [arka:trivial] justification"
+        ),
+    )
+
+
 _CHECK_DISPATCH = {
     "lint": _check_lint,
     "typecheck": _check_typecheck,
@@ -335,6 +460,7 @@ _CHECK_DISPATCH = {
     "coverage": _check_coverage,
     "security-grep": _check_security_grep,
     "spellcheck": _check_spellcheck,
+    "ui-screenshot": _check_ui_screenshot,
 }