arkaos 4.11.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.11.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

@@ -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))