arkaos 4.1.0 → 4.2.0

package/VERSION

@@ -1 +1 @@
-4.1.0
+4.2.0

package/arka/skills/flow/SKILL.md

@@ -87,6 +87,21 @@ resumes at the right gate.
   coverage read from the report file, security grep, spell-check for
   copy. Reviewers (Quality Gate personas) interpret tool output; they do
   not replace it. APPROVED/REJECTED derives from evidence.
+- **Excellence check (`excellence-mandate`, mandatory):** before closing,
+  answer three questions with evidence, not narration:
+  1. What is **unfinished** in this delivery (trimmed scope, TODO left
+     behind, parity skipped)?
+  2. What is **default** (template look, boilerplate copy, unstyled
+     component, generic strategy)?
+  3. What would a **top-tier lead reject** here? Name the benchmark
+     (`reference_companies.application` — e.g. Linear/Stripe for
+     frontend) and judge against it.
+  A non-empty answer loops the work back into Gate 3 or is escalated to
+  the operator as an explicit open-items decision. Shipping with a
+  non-empty list and no operator decision is a constitution breach.
+  Time and token cost are not acceptable answers to any of the three.
+- Quality Gate REJECTED loops back at most twice; a third REJECTED
+  escalates to the operator with the full verdict.
 - Close with an honest summary: what changed, where, how it was
   verified (real commands + results), what remains open.
 

package/config/constitution.yaml

@@ -117,14 +117,18 @@ enforcement_levels:
         rule: "When a squad lead dispatches a specialist via the Agent tool, the lead MUST emit `[arka:dispatch] <from> -> <to>` on a line of its own immediately before the dispatch call. The marker identifies the specialist to the PreToolUse specialist-enforcer so writes from the specialist pass `owner-match` instead of falling through as `no-routing-tag` or blocking the lead. The format is identical to `[arka:routing]` but uses the verb `dispatch` and points from the calling persona to the receiving specialist (e.g., `[arka:dispatch] paulo -> frontend-dev`)."
         enforcement: "PreToolUse hook (config/hooks/pre-tool-use.sh) reads the dispatch marker via core.workflow.specialist_enforcer._resolve_persona. Dispatch tag overrides routing tag because it is more specific. Without it, lead writes to specialist-owned files are blocked when hooks.specialistEnforcement=true. See ADR docs/adr/2026-05-28-specialist-dispatch-subagent-blindspot.md for the architectural constraint this rule mitigates."
 
+      # ─── Rule added in Excellence Reform (2026-07-05, operator mandate) ──
+      - id: excellence-mandate
+        rule: "Every deliverable targets excellence, not acceptance. Supervisors (leads, C-Suite, Quality Gate) and specialists are REQUIRED to be maximally critical and meticulous: no default-looking output, no unfinished edges, no lazy implementations, no delivery-for-the-sake-of-delivering. Latency and token cost are NEVER arguments against quality work — the CostGovernor hard budget is the only ceiling. Before any gate closes, the closing agent answers with evidence: 'what is unfinished, what is default, what would a top-tier lead (see reference_companies.application) reject here?' — a non-empty answer loops the work back or escalates to the operator; it is never silently shipped. UI work MUST load the frontend design skills (frontend-design, ui-ux-pro-max, project design system) at maximum effort and pass visual review against a named benchmark before reaching the Quality Gate."
+        enforcement: "G4 excellence check in arka/skills/flow/SKILL.md; frontend gate core/workflow/frontend_gate.py (flag hooks.frontendGate); QG reviewers must cite the named benchmark and enumerate concrete rejections; REJECTED redo loop capped at 2 cycles then operator escalation. Operator mandate 2026-07-05: 'não interessa se demora — o goal é excelência'."
+
   quality_gate:
     description: "Mandatory pre-delivery review. Nothing ships without APPROVED verdict."
     trigger: "After the last execution phase, before delivery to user"
     frequency: "Once per workflow execution, not per phase"
     model_policy:
-      default: sonnet
-      opus_scope: "Tier 0 diffs only: constitution, security-relevant changes, release pipeline, installer auth — or deliverables explicitly security-flagged"
-      note: "Marta's veto is model-independent: the verdict derives from the evidence report (core.governance.evidence_checks), not from model size."
+      default: best-available
+      note: "Quality Gate reviews run the best model available (frontier tier) at maximum effort by default — the Excellence Reform (2026-07-05) inverted the former sonnet-default cost posture; review quality is never the place to save tokens. User overrides per role live in ~/.arkaos/models.yaml (Model Fabric). Marta's veto is model-independent: the verdict derives from the evidence report (core.governance.evidence_checks), not from model size."
     agents:
       orchestrator:
         id: cqo-marta
@@ -140,9 +144,10 @@ enforcement_levels:
     process:
       - "Evidence engine runs first: python -m core.governance.evidence_checks — the verdict derives from its report"
       - "Marta receives all output from execution phase plus the evidence report"
-      - "Marta dispatches Eduardo (text) and Francisca (technical) in parallel to interpret the report"
-      - "Each reviewer returns a structured QGVerdict (APPROVED or REJECTED) with specific issues; evidence overall=fail forces REJECTED"
+      - "Marta dispatches Eduardo (text) and Francisca (technical) in parallel, each in an INDEPENDENT subagent context (clean context, no stake in the work being approved)"
+      - "Each reviewer returns a structured QGVerdict (APPROVED or REJECTED) with specific issues; the verdict MUST name the benchmark used (reference_companies.application) and enumerate the concrete rejections a top-tier lead would raise; evidence overall=fail forces REJECTED"
       - "If ANY reviewer rejects: work loops back to execution with issue list"
+      - "Redo loop is capped at 2 cycles: a third REJECTED escalates to the operator with the full verdict instead of another silent retry (excellence-mandate)"
       - "If ALL approve: Marta issues final APPROVED verdict"
       - "Nothing reaches the user without APPROVED from all three"
 
@@ -182,11 +187,11 @@ enforcement_levels:
         enforcement: "persistence.py exports on status change; audit detects missing exports"
 
       - id: model-routing
-        rule: "Per-tier model assignment enforced: Tier 0 opus, Tier 1/2 sonnet, mechanical haiku. Quality Gate reviewers run sonnet by default; opus ONLY for Tier 0/security-scope diffs (constitution, security, release pipeline, installer auth). Marta keeps her veto regardless of model tier."
+        rule: "Quality-first model routing: design, review, architecture, strategy, and Quality Gate phases run the BEST model available for the task (frontier tier) at maximum effort BY DEFAULT. Cheaper/smaller models (haiku, local) are reserved for genuinely mechanical work: commit messages, keyword extraction, data fetching, formatting. Cost optimisation NEVER downgrades a quality-critical phase — the CostGovernor hard budget is the only ceiling. User-owned overrides live in ~/.arkaos/models.yaml (Model Fabric): the user decides which provider/model serves each role; this rule sets the default posture, not a fixed vendor table. Replaced the cost-optimised per-tier table in the Excellence Reform (2026-07-05)."
         enforcement: "warning"
 
       - id: subagent-discipline
-        rule: "Dispatch subagents only when task requires >3 Reads or >5 Greps or isolated context. Never parallel subagents sharing state. Prefer main thread for trivial tasks."
+        rule: "Dispatch subagents only when task requires >3 Reads or >5 Greps or isolated context. Never parallel subagents sharing state. Prefer main thread for trivial tasks. EXEMPT: quality dispatches (Quality Gate reviewers, adversarial verification, design review) are never suppressed by this rule — independent review context is a correctness requirement under excellence-mandate, not an optimisation choice."
         enforcement: "warning"
 
       # ─── Rule added in PR3 Squad Intelligence Upgrade (2026-05-28) ───────
@@ -436,3 +441,6 @@ amendments:
     - version: "2.32.0"
       date: "2026-05-13"
       changes: "PR10 Conclave Phase 5 — added 7 NON-NEGOTIABLE rules (quality-over-speed, always-research, project-design-system-prerequisite, definition-of-done-per-domain, arkaos-not-yes-man, inter-agent-checkpoints, hybrid-learning) and 3 new top-level sections (definition_of_done per domain, reference_companies, tone_guide)."
+    - version: "4.2.0"
+      date: "2026-07-05"
+      changes: "Excellence Reform (operator mandate) — added excellence-mandate NON-NEGOTIABLE rule; inverted model-routing from cost-optimised tiers to quality-first (best model for design/review/architecture/strategy, user overrides in ~/.arkaos/models.yaml); QG model_policy sonnet-default → best-available; QG reviewers independent + benchmark-cited verdicts + redo loop capped at 2; subagent-discipline exempts quality dispatches."

package/config/hooks/post-tool-use.sh

@@ -49,5 +49,20 @@ if [ ! -f "$ARKAOS_ROOT/core/hooks/post_tool_use.py" ]; then
   fi
 fi
 
+# Interpreter resolution: prefer the ArkaOS venv (has pyyaml/pydantic);
+# otherwise probe — an unrelated project venv first on PATH would give a
+# python3 without yaml and silently degrade every gate.
+_PY=""
+for _cand in "$HOME/.arkaos/venv/bin/python3" "$HOME/.arkaos/.venv/bin/python3"; do
+  if [ -x "$_cand" ]; then _PY="$_cand"; break; fi
+done
+if [ -z "$_PY" ]; then
+  _PY="python3"
+  if ! "$_PY" -c "import yaml" 2>/dev/null; then
+    for _cand in /opt/homebrew/bin/python3 /usr/local/bin/python3 /usr/bin/python3; do
+      if [ -x "$_cand" ] && "$_cand" -c "import yaml" 2>/dev/null; then _PY="$_cand"; break; fi
+    done
+  fi
+fi
 PYTHONPATH="$ARKAOS_ROOT${PYTHONPATH:+:$PYTHONPATH}" \
-  exec python3 -m core.hooks.post_tool_use
+  exec "$_PY" -m core.hooks.post_tool_use

package/config/hooks/pre-tool-use.sh

@@ -52,5 +52,20 @@ if [ ! -f "$ARKAOS_ROOT/core/hooks/pre_tool_use.py" ]; then
 fi
 
 # ─── Single python process; stdin/stdout/stderr/exit-code pass through ──
+# Interpreter resolution: prefer the ArkaOS venv (has pyyaml/pydantic);
+# otherwise probe — an unrelated project venv first on PATH would give a
+# python3 without yaml and silently degrade every gate.
+_PY=""
+for _cand in "$HOME/.arkaos/venv/bin/python3" "$HOME/.arkaos/.venv/bin/python3"; do
+  if [ -x "$_cand" ]; then _PY="$_cand"; break; fi
+done
+if [ -z "$_PY" ]; then
+  _PY="python3"
+  if ! "$_PY" -c "import yaml" 2>/dev/null; then
+    for _cand in /opt/homebrew/bin/python3 /usr/local/bin/python3 /usr/bin/python3; do
+      if [ -x "$_cand" ] && "$_cand" -c "import yaml" 2>/dev/null; then _PY="$_cand"; break; fi
+    done
+  fi
+fi
 PYTHONPATH="$ARKAOS_ROOT${PYTHONPATH:+:$PYTHONPATH}" \
-  exec python3 -m core.hooks.pre_tool_use
+  exec "$_PY" -m core.hooks.pre_tool_use

package/config/hooks/session-start.sh

@@ -120,6 +120,28 @@ if [ -n "$REPO" ] && command -v python3 &>/dev/null; then
   fi
 fi
 
+# ─── Dashboard ensure (v4.1.2) ──────────────────────────────────────────
+# Safety net for the login autostart (`npx arkaos autostart enable`): if the
+# dashboard is healthy this is two curl health checks (~50ms); if not, it
+# starts API+UI. Background + disown so it never touches the 5s budget.
+# Toggle off: ~/.arkaos/config.json -> {"dashboard": {"ensure_on_session": false}}
+if [ -n "$REPO" ] && [ -f "$REPO/scripts/start-dashboard.sh" ]; then
+  _DASH_ENSURE=$(python3 -c "import json; print(json.load(open('$HOME/.arkaos/config.json')).get('dashboard',{}).get('ensure_on_session', True))" 2>/dev/null || echo "True")
+  if [ "$_DASH_ENSURE" = "True" ] || [ "$_DASH_ENSURE" = "true" ]; then
+    mkdir -p "$HOME/.arkaos/logs"
+    (
+      # GNU `timeout` is absent on stock macOS — degrade to an unbounded
+      # run; the launcher itself is bounded (health wait + start).
+      if command -v timeout >/dev/null 2>&1; then
+        ARKAOS_NO_BROWSER=1 timeout 90s bash "$REPO/scripts/start-dashboard.sh" ensure >> "$HOME/.arkaos/logs/dashboard-ensure.log" 2>&1
+      else
+        ARKAOS_NO_BROWSER=1 bash "$REPO/scripts/start-dashboard.sh" ensure >> "$HOME/.arkaos/logs/dashboard-ensure.log" 2>&1
+      fi
+    ) &
+    disown 2>/dev/null || true
+  fi
+fi
+
 # --- Session Memory Resume Context ---
 if command -v python3 &>/dev/null && [ -n "$REPO" ]; then
   _SESSION_CTX=$(cd "$REPO" && python3 -c "

package/config/hooks/stop.sh

@@ -49,6 +49,21 @@ if [ ! -f "$ARKAOS_ROOT/core/hooks/stop.py" ]; then
   fi
 fi
 
+# Interpreter resolution: prefer the ArkaOS venv (has pyyaml/pydantic);
+# otherwise probe — an unrelated project venv first on PATH would give a
+# python3 without yaml and silently degrade every gate.
+_PY=""
+for _cand in "$HOME/.arkaos/venv/bin/python3" "$HOME/.arkaos/.venv/bin/python3"; do
+  if [ -x "$_cand" ]; then _PY="$_cand"; break; fi
+done
+if [ -z "$_PY" ]; then
+  _PY="python3"
+  if ! "$_PY" -c "import yaml" 2>/dev/null; then
+    for _cand in /opt/homebrew/bin/python3 /usr/local/bin/python3 /usr/bin/python3; do
+      if [ -x "$_cand" ] && "$_cand" -c "import yaml" 2>/dev/null; then _PY="$_cand"; break; fi
+    done
+  fi
+fi
 PYTHONPATH="$ARKAOS_ROOT${PYTHONPATH:+:$PYTHONPATH}" \
-  python3 -m core.hooks.stop
+  "$_PY" -m core.hooks.stop
 exit 0

package/config/hooks/user-prompt-submit.sh

@@ -54,5 +54,20 @@ if [ ! -f "$ARKAOS_ROOT/core/hooks/user_prompt_submit.py" ]; then
   fi
 fi
 
+# Interpreter resolution: prefer the ArkaOS venv (has pyyaml/pydantic);
+# otherwise probe — an unrelated project venv first on PATH would give a
+# python3 without yaml and silently degrade every gate.
+_PY=""
+for _cand in "$HOME/.arkaos/venv/bin/python3" "$HOME/.arkaos/.venv/bin/python3"; do
+  if [ -x "$_cand" ]; then _PY="$_cand"; break; fi
+done
+if [ -z "$_PY" ]; then
+  _PY="python3"
+  if ! "$_PY" -c "import yaml" 2>/dev/null; then
+    for _cand in /opt/homebrew/bin/python3 /usr/local/bin/python3 /usr/bin/python3; do
+      if [ -x "$_cand" ] && "$_cand" -c "import yaml" 2>/dev/null; then _PY="$_cand"; break; fi
+    done
+  fi
+fi
 PYTHONPATH="$ARKAOS_ROOT${PYTHONPATH:+:$PYTHONPATH}" \
-  exec python3 -m core.hooks.user_prompt_submit
+  exec "$_PY" -m core.hooks.user_prompt_submit

package/config/models.yaml

@@ -0,0 +1,70 @@
+# ═══════════════════════════════════════════════════════════════════════
+# ArkaOS Model Fabric — who runs what.
+#
+# Your copy lives at ~/.arkaos/models.yaml (created by `npx arkaos models
+# init`; this file is the packaged default). Edit it directly or use:
+#
+#   npx arkaos models                 show every role and what it resolves to
+#   npx arkaos models set review anthropic/best
+#   npx arkaos models set mechanical ollama/qwen3:8b
+#
+# The interactive runtime (Claude Code, Codex, Gemini, Cursor) keeps its
+# own main-loop model — roles govern everything ArkaOS itself dispatches:
+# subagents, Quality Gate, Forge, fusion, cognition, daemons.
+#
+# Constitution `model-routing` (Excellence Reform 2026-07-05): quality-
+# critical roles run the BEST model available by default; only genuinely
+# mechanical work economises. Change the mapping, not the posture.
+# ═══════════════════════════════════════════════════════════════════════
+version: 1
+
+# ─── Providers ──────────────────────────────────────────────────────────
+# type must match a provider in core/runtime/llm_provider.py.
+providers:
+  runtime:
+    type: subagent          # shell out to the active runtime CLI
+  anthropic:
+    type: anthropic-direct  # SDK; needs ANTHROPIC_API_KEY
+  ollama:
+    type: ollama            # local models, http://localhost:11434
+  # openrouter:             # one key -> hundreds of models (Model Fabric PR-B)
+  #   type: openrouter
+
+# ─── Aliases ────────────────────────────────────────────────────────────
+# `best` / `default` / `fast` resolve per provider, so roles stay readable.
+aliases:
+  runtime:
+    best: opus
+    default: sonnet
+    fast: haiku
+  anthropic:
+    best: claude-opus-4-8
+    default: claude-sonnet-5
+    fast: claude-haiku-4-5-20251001
+  ollama:
+    best: ""                # set your strongest local model, e.g. kimi-k2.6
+    default: ""
+    fast: ""
+
+# ─── Roles ──────────────────────────────────────────────────────────────
+# provider/model per kind of work. `model` is an alias above or a literal
+# model id. `effort`: low | medium | high | max.
+roles:
+  design:       {provider: runtime, model: best,    effort: max}
+  review:       {provider: runtime, model: best,    effort: max}
+  architecture: {provider: runtime, model: best,    effort: max}
+  strategy:     {provider: runtime, model: best,    effort: max}
+  quality_gate: {provider: runtime, model: best,    effort: max}
+  execution:    {provider: runtime, model: default, effort: high}
+  mechanical:   {provider: runtime, model: fast,    effort: low}
+
+# ─── Fusion (Model Fabric PR-D) ─────────────────────────────────────────
+# Panel answers in parallel; the judge analyses consensus, contradictions
+# and blind spots, then synthesises. Empty panel = fusion disabled.
+fusion:
+  judge: {provider: runtime, model: best, effort: max}
+  panel: []
+  # panel:
+  #   - {provider: ollama, model: kimi-k2.6}
+  #   - {provider: openrouter, model: deepseek/deepseek-v4-pro}
+  #   - {provider: anthropic, model: best}

package/core/hooks/pre_tool_use.py

@@ -5,10 +5,12 @@ with ONE python process. Gate order is preserved exactly:
 
     1. KB-first research gate  (core/workflow/research_gate.py)
     2. Specialist-dispatch gate (core/workflow/specialist_enforcer.py)
-    3. Fast allow for non-flow-gated tools
-    4. CostGovernor budget check (stdlib-only — MUST run even when the
+    3. Frontend excellence gate (core/workflow/frontend_gate.py — v4.2.0
+       excellence-mandate: UI edits require [arka:design] evidence)
+    4. Fast allow for non-flow-gated tools
+    5. CostGovernor budget check (stdlib-only — MUST run even when the
        yaml-needing enforcers degrade; see ADR 2026-07-04-cost-governor)
-    5. Evidence-flow gate (core/workflow/flow_enforcer.py)
+    6. Evidence-flow gate (core/workflow/flow_enforcer.py)
 
 Behavior contract (unchanged from the bash version):
     - allow  → no stdout, exit 0 (nudges/warnings on stderr)
@@ -165,6 +167,50 @@ def _specialist_gate(
     return None
 
 
+def _frontend_gate(
+    root: str,
+    tool_name: str,
+    transcript_path: str,
+    session_id: str,
+    cwd: str,
+    tool_input: dict,
+    messages: _MessagesOnce,
+) -> int | None:
+    """Frontend excellence gate (excellence-mandate). 2 on deny, None to continue."""
+    if tool_name not in _SPECIALIST_TOOLS:
+        return None
+    if not (Path(root) / "core" / "workflow" / "frontend_gate.py").is_file():
+        return None
+    try:
+        from core.workflow.frontend_gate import (
+            evaluate,
+            is_ui_file,
+            record_telemetry,
+        )
+    except Exception:
+        return None  # frontend-gate-import-failed → allow
+    # Zero-read fast path: only UI files ever need the transcript.
+    if not is_ui_file(str(tool_input.get("file_path", ""))):
+        return None
+    decision = evaluate(
+        tool_name=tool_name,
+        transcript_path=transcript_path,
+        session_id=session_id,
+        cwd=cwd,
+        tool_input=tool_input,
+        messages=messages.load(),
+    )
+    try:
+        record_telemetry(session_id=session_id, tool=tool_name, decision=decision)
+    except Exception:
+        pass
+    if not decision.allow:
+        return _deny(decision.to_stderr_message())
+    if decision.to_stderr_message():
+        print(decision.to_stderr_message(), file=sys.stderr)
+    return None
+
+
 def _budget_check(session_id: str) -> tuple[bool, str]:
     """CostGovernor gate (stdlib-only). Returns (allow, warning)."""
     try:
@@ -244,6 +290,12 @@ def main(stdin_json: dict | None = None) -> int:
     if code is not None:
         return code
 
+    code = _frontend_gate(
+        root, tool_name, transcript_path, session_id, cwd, tool_input, messages
+    )
+    if code is not None:
+        return code
+
     # Fast allow: not a flow-gated tool (Bash stays — classified per-command
     # by the enforcer via bash_is_effect()).
     if tool_name not in _FLOW_GATED_TOOLS:

package/core/obsidian/relator.py

@@ -36,6 +36,13 @@ _STOPWORDS = frozenset({
 })
 
 
+# Jaccard between full documents rarely exceeds ~0.3 even for clearly
+# related notes, while cosine similarity of embeddings sits comfortably
+# above 0.5. A single threshold calibrated for cosine silently disabled
+# the relator on every machine without fastembed (v4.1.1 fix).
+_KEYWORD_MIN_SIMILARITY = 0.15
+
+
 def find_related(
     content: str,
     vault: Path,
@@ -48,8 +55,9 @@ def find_related(
     candidates = _collect_notes(vault, exclude)
     if not candidates:
         return []
-    scored = _score_candidates(content, candidates)
-    filtered = [r for r in scored if r.score >= min_similarity]
+    scored, method = _score_candidates(content, candidates)
+    threshold = min_similarity if method == "semantic" else _KEYWORD_MIN_SIMILARITY
+    filtered = [r for r in scored if r.score >= threshold]
     filtered.sort(key=lambda r: r.score, reverse=True)
     return filtered[:top_n]
 
@@ -70,22 +78,24 @@ def _collect_notes(vault: Path, exclude: Optional[Path]) -> list[tuple[Path, str
 
 def _score_candidates(
     content: str, candidates: list[tuple[Path, str]]
-) -> list[RelatedNote]:
+) -> tuple[list[RelatedNote], str]:
+    """Score candidates, returning (results, method) so the caller can
+    apply a threshold appropriate to the scoring space."""
     try:
         return _semantic_score(content, candidates)
     except Exception:
-        return _keyword_score(content, candidates)
+        return _keyword_score(content, candidates), "keyword"
 
 
 def _semantic_score(
     content: str, candidates: list[tuple[Path, str]]
-) -> list[RelatedNote]:
+) -> tuple[list[RelatedNote], str]:
     from core.knowledge.embedder import embed, is_available
     if not is_available():
-        return _keyword_score(content, candidates)
+        return _keyword_score(content, candidates), "keyword"
     query_emb = embed(content)
     if query_emb is None:
-        return _keyword_score(content, candidates)
+        return _keyword_score(content, candidates), "keyword"
     results = []
     for path, text in candidates:
         note_emb = embed(text[:2000])
@@ -96,7 +106,7 @@ def _semantic_score(
             path=path, title=_title_from_path(path),
             score=score, excerpt=text[:160],
         ))
-    return results
+    return results, "semantic"
 
 
 def _keyword_score(