arkaos 4.10.0 → 4.12.0

package/README.md

@@ -2,7 +2,7 @@
 
 **The Operating System for AI Agent Teams.**
 
-82 agents. 17 departments. 268 skills. Enterprise frameworks. Multi-runtime. One install.
+82 agents. 17 departments. 270 skills. Enterprise frameworks. Multi-runtime. One install.
 
 ```bash
 npx arkaos install

package/VERSION

@@ -1 +1 @@
-4.10.0
+4.12.0

package/arka/SKILL.md

@@ -25,7 +25,7 @@ measures citation compliance per turn.
 # ArkaOS — Main Orchestrator
 
 > **The Operating System for AI Agent Teams**
-> 82 agents. 17 departments. 268 skills. Multi-runtime. Dashboard. Knowledge RAG.
+> 82 agents. 17 departments. 270 skills. Multi-runtime. Dashboard. Knowledge RAG.
 
 ## ⛔ Evidence flow — 4 gates (NON-NEGOTIABLE)
 
@@ -187,6 +187,8 @@ violation (squad-routing, arka-supremacy, spec-driven, mandatory-qa).
 | `/arka keys` | Manage API keys (OpenAI, Google, fal.ai) |
 | `/arka personas` | Manage AI personas (create, clone to agent) |
 | `/arka resume <PR_URL>` | Re-enter the Claude Code session that produced a PR (GitHub / GitLab / Bitbucket). Wraps the native `/resume` from Claude Code 2.1.122+. Useful with `arka-dev-spec` and `arka-release` archaeology. |
+| `/arka refine <rough idea>` | Turn a vague or domain-unfamiliar ask into a precise English prompt by asking about the topic first (arka-refine). Auto-suggested on vague requests. |
+| `/arka recipes [list\|show\|apply] <slug>` | Reuse validated QG-approved feature builds (arka-recipes). Synapse L7.6 auto-surfaces matches. |
 | `/do <description>` | Universal routing — natural language to department command |
 
 ## Universal Orchestrator (/do)
@@ -210,6 +212,13 @@ Users don't need to memorize commands. Just describe what you need:
 2. Natural language → Synapse L1 (keyword) + L5 (command hints) + hook context tags
 3. Resolution: single match → announce + execute | multiple → top 3 + ask | ambiguous → ask department
 4. Code-modifying → preview + confirm | non-code → auto-execute
+5. **Vague request → refine first.** When the ask is vague (the
+   UserPromptSubmit hook injected `[arka:refine-suggested]`, or there is
+   no clear target/scope/acceptance criteria — common in a domain the
+   user does not command, e.g. UI/design), route to `/arka refine`
+   BEFORE the department: it asks about the topic and compiles a precise
+   English prompt, then dispatches back through `/do`. A request that is
+   already specific skips refinement.
 
 ### Squad Routing (MUST)
 

package/arka/skills/flow/SKILL.md

@@ -56,7 +56,8 @@ resumes at the right gate.
   anything substantive they do not cover. Cite what you use with
   `[[wikilinks]]` or `file:line`; declare gaps explicitly.
 - Read the live context: profile, CLAUDE.md, git branch, cwd tag,
-  pattern cards (L7.5), agent experiences (L2.6).
+  pattern cards (L7.5), validated recipes (L7.6 — QG-approved prior
+  builds to adapt), agent experiences (L2.6).
 
 ### Gate 2 — PLAN `[arka:gate:2]`
 
@@ -65,6 +66,20 @@ resumes at the right gate.
 - Complexity is scored by `core/forge/complexity.py`: LOW → a plan
   inline in the reply; MEDIUM/HIGH → persist the plan to
   `~/.arkaos/plans/` + Obsidian and consider `/arka-forge`.
+- **Plan-judge (constitution `gate-judges`, MEDIUM/HIGH only):** BEFORE
+  presenting the plan to the user, dispatch one judge via the Agent
+  tool with `JUDGE_VERDICT_JSON_SCHEMA` from `core.governance.judge` as
+  the structured-output schema, frontier model (constitution
+  `quality_gate.model_policy`). The judge receives the original request
+  + the plan and hunts adversarially for what is unfinished, default,
+  or would be rejected by a top-tier lead — the same
+  `arkaos-not-yes-man` standard applied to the AGENT's work. `REVISE`
+  → fix the plan and re-judge (max 2 loops, then escalate the findings
+  to the user). A non-empty `user_challenge` means the USER's request
+  itself is technically wrong — present the challenge alongside the
+  plan, never swallow it. Record every verdict:
+  `arka-py -m core.evals.record_cli --kind judge`. LOW/trivial work
+  skips the judge — gates catch risk, they do not ritualize.
 - **Wait for EXPLICIT user approval. Silence is not approval.** This is
   the one human gate and it never disappears.
 - Non-blocking unknowns do not stall the gate: proceed and state
@@ -97,6 +112,13 @@ 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.
+- **Output-judge (constitution `gate-judges`, MEDIUM/HIGH only):**
+  BEFORE dispatching the Quality Gate personas, dispatch one judge
+  (Agent tool, `JUDGE_VERDICT_JSON_SCHEMA`, frontier model) over the
+  deliverable + diff + evidence report. `REVISE` loops the work back
+  into Gate 3 (max 2); `PASS` and its findings become INPUT to the QG
+  reviewers — the judge never replaces the personas or the evidence.
+  Record the verdict: `arka-py -m core.evals.record_cli --kind judge`.
 - **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

package/arka/skills/recipes/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: arka-recipes
+description: >
+  Validated recipe library — QG-approved feature builds captured with
+  their reference files, reused across projects instead of re-derived
+  from docs. Lists, shows, and applies recipes (Laravel login, payment
+  integration, standard UI patterns…).
+  TRIGGER: "/arka recipes", "que receitas temos", "apply the <x> recipe",
+  "reusa a receita", "há uma receita para isto?", "recipe for <feature>".
+  SKIP: capturing a NEW recipe from an approved deliverable -> the
+  Quality Gate skill step 7 proposes it; short reusable text hints ->
+  the Pattern Library (record_pattern); planning a task -> arka-forge.
+allowed-tools: [Read, Bash]
+---
+
+<!-- arka:kb-first-prefix begin -->
+> **KB-first:** query `mcp__obsidian__search_notes` and cite
+> `[[wikilinks]]` — or declare the gap — BEFORE any external research.
+> Full doctrine: `arka/SKILL.md` (KB-First Research).
+<!-- arka:kb-first-prefix end -->
+
+# /arka recipes — reuse validated feature builds
+
+A recipe is a QG-approved feature captured with its reference files
+(`~/.arkaos/recipes/<slug>/{RECIPE.md, recipe.json, files/}`). Where a
+pattern card is a text hint, a recipe is proven code to adapt — so
+"Laravel login" is a known, validated build, not a from-scratch
+re-derivation. Synapse L7.6 auto-injects matching recipes as
+`[recipes:N]` on every prompt; these commands drive them explicitly.
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `/arka recipes list` | List captured recipes (slug · stack · name). |
+| `/arka recipes show <slug>` | Print a recipe's full metadata (recipe.json). |
+| `/arka recipes apply <slug>` | Read RECIPE.md + files/ as prior art and adapt to the current project through the normal 4-gate flow. |
+
+Backed by `core.knowledge.recipes_cli`:
+
+    arka-py -m core.knowledge.recipes_cli list
+    arka-py -m core.knowledge.recipes_cli show <slug>
+
+## Applying a recipe (never copy-paste blind)
+
+`apply <slug>` is prior-art-driven adaptation, not a code dump:
+
+1. Read `~/.arkaos/recipes/<slug>/RECIPE.md` (problem, approach,
+   decisions) and the files under `files/`.
+2. Read `recipe.json` `apply_notes` — the recorded per-project
+   adaptation contract (namespaces, models, config to swap).
+3. Enter the normal flow: Gate 2 presents a plan that maps the recipe
+   onto THIS project's stack and conventions; the user approves it like
+   any other build. The recipe informs the plan; it does not bypass the
+   gates.
+4. Implement, run the recipe's acceptance criteria as the test floor,
+   pass the Quality Gate.
+
+## Capture is elsewhere
+
+New recipes are proposed by the Quality Gate (step 7) on an APPROVED
+reusable feature and captured fail-closed (every field sanitized,
+refused without a redaction config). This skill only consumes them.
+
+## Related
+
+- Pattern Library (Synapse L7.5) — short reusable text hints.
+- `arka-dev-spec` / `/dev feature` — the flow an `apply` runs through.
+- `arka-forge` — planning when the adaptation is complex.

package/arka/skills/refine/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: arka-refine
+description: >
+  Prompt refiner for vague or domain-unfamiliar requests — turns a rough
+  ask into a high-quality English prompt for the workflow by asking
+  targeted questions first. For users who cannot phrase a clear brief in
+  a domain they do not command (UI/design, infra, data modelling).
+  TRIGGER: "/arka refine", "refina o prompt", "ajuda-me a pedir",
+  "não sei explicar o que quero", and any vague request the /do
+  orchestrator routes here (hook marker "[arka:refine-suggested]").
+  SKIP: the request is already specific with clear scope and acceptance
+  criteria -> /do dispatches directly; multi-agent planning of a known
+  task -> arka-forge; requirements spec for code -> arka-dev-spec.
+allowed-tools: [Read, AskUserQuestion, Skill]
+---
+
+<!-- arka:kb-first-prefix begin -->
+> **KB-first:** query `mcp__obsidian__search_notes` and cite
+> `[[wikilinks]]` — or declare the gap — BEFORE any external research.
+> Full doctrine: `arka/SKILL.md` (KB-First Research).
+<!-- arka:kb-first-prefix end -->
+
+# /arka refine — turn a rough ask into a quality prompt
+
+A vague request produces a vague build. This skill closes the gap by
+asking about the TOPIC before any work starts, then compiling a precise
+English prompt the workflow can execute. It exists for the case the
+operator named: *"I don't understand UI/design, so I can never write an
+input clear enough to build the right thing."*
+
+## When it runs
+
+- Explicitly: the user types `/arka refine <rough idea>`.
+- Automatically: the `/do` orchestrator routes a vague request here
+  BEFORE the department, or the UserPromptSubmit hook injects
+  `[arka:refine-suggested] score=N` for a vague ask (high ambiguity and
+  no concrete target named). Interposition is a suggestion — announce it
+  and proceed only if refinement genuinely helps; a clear ask goes
+  straight to `/do`.
+
+## The refinement loop (conversation, not a form)
+
+1. **Identify the topic and the domain.** Name what is being built and
+   which domain expertise it needs (frontend/design, data, infra, copy…).
+2. **Ask ONE substantive question per turn.** Open dialogue, never a
+   multiple-choice menu as a substitute for conversation. Each question
+   teaches while it asks — in a domain the user does not command, carry
+   the vocabulary so they can answer:
+   - **UI/design:** load `frontend-design` / `ui-ux-pro-max` first. Ask
+     in their terms — visual tone (minimal / editorial / brutalist),
+     density, a named benchmark to match ("closer to Linear or to
+     Notion?"), light/dark, the one screen that matters most.
+   - Other domains: mirror the same pattern with that field's vocabulary.
+3. **Stop at ~5 questions.** Enough to remove ambiguity, not an
+   interrogation. If the user says "just decide", pick sensible defaults
+   and state them as assumptions.
+4. **Compile the final prompt IN ENGLISH.** Show it in a fenced block:
+   objective, scope, explicit non-goals, the named benchmark, acceptance
+   criteria, and stack/constraints gathered. English is the workflow's
+   working language regardless of the conversation language.
+5. **Dispatch only after an explicit OK.** On approval, hand the compiled
+   prompt to `/do` — which enters the normal 4-gate flow (the compiled
+   prompt is the Gate-2 input; approval of the refinement is not approval
+   of the eventual plan).
+
+## Guardrails
+
+- Never invent requirements the user did not confirm; a stated assumption
+  is fine, a fabricated constraint is not.
+- Never skip straight to building — the deliverable of THIS skill is the
+  prompt, not the feature.
+- Be critical: if the request is technically wrong or would ship a worse
+  product, challenge it here (pushback protocol, `arkaos-not-yes-man`)
+  before compiling.
+
+## Related
+
+- `frontend-design`, `ui-ux-pro-max` — design vocabulary for UI prompts.
+- `/do` — receives the compiled prompt and routes it.
+- `arka-dev-spec` — when the refined ask needs a full code spec at Gate 2.
+- `arka-forge` — when the refined ask needs multi-agent planning.

package/config/constitution.yaml

@@ -121,6 +121,11 @@ enforcement_levels:
         rule: "Quality Gate REJECTED verdicts MUST result in an Experience record for the failing agent, written to ~/.arkaos/agents/<agent_id>/experiences.jsonl via core.governance.cqo_experience_recorder. Next dispatch of that agent loads the experiences via the Synapse L2.6 layer (core.synapse.agent_experiences_layer) so the lesson carries across sessions. Without this, REJECTED reports evaporate as conversation turns and the same structural mistakes recur."
         enforcement: "PR3 v3.74.0 ships the storage, parser, and Synapse layer. v3.74.1 will wire a PostToolUse hook on the Agent tool that auto-records on REJECTED verdicts. Until then orchestrators MUST call cqo_experience_recorder.record_from_verdict() after every CQO dispatch. Audit via ~/.arkaos/bin/arka-py -m core.governance.agent_experiences_cli list <agent_id>."
 
+      # ─── Rule added in Interaction Reform PR2 (2026-07-09) ──────────────
+      - id: gate-judges
+        rule: "MEDIUM/HIGH work runs two gate judges: a plan-judge at Gate 2 (judges the planning summary BEFORE it reaches the user) and an output-judge at Gate 4 (judges the deliverable BEFORE the Quality Gate personas). Judges return a structured JudgeVerdict (core.governance.judge, PASS/REVISE binary, REVISE requires actionable findings) on a frontier-tier model, apply the arkaos-not-yes-man standard to the AGENT's work, and surface a user_challenge when the USER's request itself is technically wrong. REVISE loops the work (max 2, then escalate). LOW/trivial work skips the judges — gates catch risk, they do not ritualize."
+        enforcement: "Instructional in arka/skills/flow/SKILL.md (Gates 2 and 4) and departments/quality/SKILL.md (step 0); every verdict recorded to ~/.arkaos/telemetry/judge-verdicts.jsonl via core.evals.record_cli --kind judge — the PASS/REVISE telemetry decides whether a hook-level enforcement consumer is warranted."
+
       # ─── Rule added in PR-4 of the prompt-surface plan (2026-07-08) ─────
       - id: persona-vs-artifact
         rule: "An agent's persona lives in the conversation, never in the deliverable. User- or client-facing artifacts (emails, copy, code comments, docs, posts, reports handed to a client) are written in the style the CONTEXT and the client's brand demand, not in the agent's personality. Agents also never meta-reference their own persona or behavioral profile in output ('as a C+D analyst, I...') — the persona shows in behavior, it is not announced."
@@ -483,3 +488,6 @@ amendments:
     - version: "4.7.0"
       date: "2026-07-08"
       changes: "Constitution 2.0 (PR-5 prompt-surface, operator-approved plan): re-tiered the top enforcement level 26 -> 6 by the gate-verifiability admission test (16 -> MUST, 4 -> SHOULD; rule text preserved verbatim, total 46 rules unchanged); rewrote arkaos-not-yes-man with epistemic-branch pushback + anti-submission (PR-4); added persona-vs-artifact MUST (PR-4); added autonomy section (4-level confirmation taxonomy, assuming_pattern, default_stance); added claim-level verdict field (CONFIRMED/PLAUSIBLE/REFUTED) to QGBlocker."
+    - version: "4.12.0"
+      date: "2026-07-09"
+      changes: "Interaction Reform PR2 (operator-approved plan, 2026-07-09): added gate-judges MUST rule — plan-judge at Gate 2 and output-judge at Gate 4 for MEDIUM/HIGH work, structured JudgeVerdict (core.governance.judge), frontier tier, arkaos-not-yes-man standard applied to agents, user_challenge surfacing for technically wrong requests; verdicts recorded to judge-verdicts.jsonl."

package/config/mcp-policy.yaml

@@ -12,6 +12,7 @@ policies:
   - match:
       stack_includes: [laravel, php]
     active:
+      - codebase-memory
       - arka-prompts
       - obsidian
       - context7
@@ -42,6 +43,7 @@ policies:
   - match:
       stack_includes: [nuxt, vue]
     active:
+      - codebase-memory
       - arka-prompts
       - obsidian
       - context7
@@ -72,6 +74,7 @@ policies:
   - match:
       stack_includes: [next, react]
     active:
+      - codebase-memory
       - arka-prompts
       - obsidian
       - context7
@@ -111,6 +114,7 @@ policies:
       - mirakl
       - sentry
     deferred:
+      - codebase-memory
       - memory-bank
       - postgres
       - supabase
@@ -132,6 +136,7 @@ policies:
   - match:
       stack_includes: [python]
     active:
+      - codebase-memory
       - arka-prompts
       - obsidian
       - context7
@@ -169,6 +174,7 @@ policies:
       - firecrawl
       - clickup
     deferred:
+      - codebase-memory
       - memory-bank
       - gh-grep
       - postgres
@@ -198,6 +204,7 @@ policies:
       - canva
       - firecrawl
     deferred:
+      - codebase-memory
       - memory-bank
       - gh-grep
       - postgres
@@ -227,6 +234,7 @@ policies:
       - context7
       - gh-grep
     deferred:
+      - codebase-memory
       - memory-bank
       - postgres
       - supabase

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

@@ -0,0 +1,96 @@
+"""Record a QGVerdict or gate JudgeVerdict as an eval label.
+
+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
+recorded silently would poison the corpus.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from pydantic import ValidationError
+
+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="")
+    parser.add_argument("--session-id", default="")
+    args = parser.parse_args(argv)
+
+    raw = (
+        Path(args.file).read_text(encoding="utf-8")
+        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,
+        department=args.department,
+        eval_task_id=args.eval_task_id,
+        session_id=args.session_id,
+    )
+    print(json.dumps({
+        "recorded": True,
+        "verdict": verdict.verdict,
+        "eval_task_id": args.eval_task_id,
+    }))
+    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/runner_cli.py

@@ -0,0 +1,102 @@
+"""Eval runner CLI — list tasks, corpus status, dispatch-ready prompts.
+
+Evals reuse the Quality Gate as the judge (ADR 2026-07-09): a run is
+the orchestrator dispatching a task prompt through the normal squad
+flow, then recording the QGVerdict with the task id via
+``core.evals.record_cli``. This CLI is the deterministic half — it
+never invokes models itself.
+
+Usage:
+    arka-py -m core.evals.runner_cli list [--department dev]
+    arka-py -m core.evals.runner_cli status
+    arka-py -m core.evals.runner_cli prompt <task-id>
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+from core.evals.schema import EvalTask, load_eval_tasks
+from core.evals.verdict_labels import load_verdict_labels
+
+DISTILLATION_LABEL_GATE = 500  # ADR 2026-07-09-evals-and-distillation
+
+
+def _cmd_list(department: str | None) -> int:
+    tasks = load_eval_tasks()
+    if department:
+        tasks = [t for t in tasks if t.department == department]
+    for task in tasks:
+        print(f"{task.id:35s} {task.department:10s} {task.prompt[:60].strip()}…")
+    print(f"\n{len(tasks)} task(s)")
+    return 0
+
+
+def _cmd_status() -> int:
+    labels = load_verdict_labels()
+    verdicts = [str(entry.get("verdict", "")) for entry in labels]
+    by_dept: dict[str, int] = {}
+    linked = 0
+    for entry in labels:
+        dept = str(entry.get("department") or "(none)")
+        by_dept[dept] = by_dept.get(dept, 0) + 1
+        if entry.get("eval_task_id"):
+            linked += 1
+    total = len(labels)
+    print(f"labels: {total} (gate: {DISTILLATION_LABEL_GATE} — "
+          f"{max(0, DISTILLATION_LABEL_GATE - total)} to go)")
+    print(f"  APPROVED: {verdicts.count('APPROVED')}  "
+          f"REJECTED: {verdicts.count('REJECTED')}")
+    print(f"  linked to eval tasks: {linked}")
+    for dept, count in sorted(by_dept.items()):
+        print(f"  {dept}: {count}")
+    print(f"eval tasks defined: {len(load_eval_tasks())}")
+    return 0
+
+
+def _dispatch_prompt(task: EvalTask) -> str:
+    properties = "\n".join(f"- {p}" for p in task.expected_properties)
+    rubric = f"\nRubrica adicional: {task.rubric}" if task.rubric else ""
+    return (
+        f"[EVAL RUN — task {task.id}]\n"
+        f"Departamento: {task.department}\n\n"
+        f"Tarefa: {task.prompt}\n\n"
+        f"O deliverable será julgado pelo Quality Gate contra estas "
+        f"propriedades verificáveis:\n{properties}{rubric}\n\n"
+        f"Após o verdict, regista o label com:\n"
+        f"  arka-py -m core.evals.record_cli --eval-task-id {task.id} "
+        f"--department {task.department} < verdict.json"
+    )
+
+
+def _cmd_prompt(task_id: str) -> int:
+    tasks = {t.id: t for t in load_eval_tasks()}
+    task = tasks.get(task_id)
+    if task is None:
+        print(f"error: unknown eval task {task_id!r}; run `list`",
+              file=sys.stderr)
+        return 1
+    print(_dispatch_prompt(task))
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    sub = parser.add_subparsers(dest="cmd", required=True)
+    p_list = sub.add_parser("list")
+    p_list.add_argument("--department")
+    sub.add_parser("status")
+    p_prompt = sub.add_parser("prompt")
+    p_prompt.add_argument("task_id")
+    args = parser.parse_args(argv)
+
+    if args.cmd == "list":
+        return _cmd_list(args.department)
+    if args.cmd == "status":
+        return _cmd_status()
+    return _cmd_prompt(args.task_id)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())