arkaos 4.6.0 → 4.7.1

package/core/agents/behavioral_compiler.py

@@ -0,0 +1,294 @@
+"""Behavioral compiler: agent YAML → runtime subagent markdown (PR-4).
+
+The 2026-07-08 frontier prompt audit found that psychometric tables
+(DISC scores, Big Five 0-100, MBTI) never reach the model and cannot be
+operationalized by it — zero production prompts from any frontier lab
+use trait taxonomies; all use behavioral specification. This compiler
+keeps the 4-framework DNA as the DESIGN-TIME source (it differentiates
+82 agents) and emits the RUNTIME translation: conditional rules, a
+lexical blacklist, a disagreement/escalation protocol with an exit
+condition, and the persona-vs-artifact contract.
+
+Single source: `departments/<dept>/agents/<slug>.yaml`. Output:
+`config/claude-agents/<slug>.md` (what the installer copies into every
+project's `.claude/agents/`). Hand-written prompts in _HAND_WRITTEN are
+never overwritten. `tests/python/test_behavioral_compiler.py` locks
+committed output byte-identical to `compile_agent()` of its YAML.
+
+CLI:
+    arka-py -m core.agents.behavioral_compiler --check   # drift check
+    arka-py -m core.agents.behavioral_compiler --write   # (re)generate
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+import yaml
+
+_ROOT = Path(__file__).resolve().parents[2]
+_OUT_DIR = _ROOT / "config" / "claude-agents"
+
+# Best hand-authored prompts in the repo (QG + dev lead) — the compiler
+# must never clobber them.
+_HAND_WRITTEN = {"marta-cqo", "eduardo-copy", "francisca-tech", "paulo-tech-lead"}
+
+# Pilot scope: dev department. tech-lead maps to the hand-written
+# paulo-tech-lead.md and is excluded.
+_PILOT_YAMLS: tuple[str, ...] = (
+    "departments/dev/agents/architect.yaml",
+    "departments/dev/agents/backend-dev.yaml",
+    "departments/dev/agents/dba.yaml",
+    "departments/dev/agents/devops-eng.yaml",
+    "departments/dev/agents/frontend-dev.yaml",
+    "departments/dev/agents/qa-eng.yaml",
+    "departments/dev/agents/research-assistant.yaml",
+    "departments/dev/agents/security-eng.yaml",
+)
+
+# Standard behavioral blocks imported from the frontier audit (Obsidian:
+# "Projects/WizardingCode Internal/ArkaOS/Prompt Audit —
+# system_prompts_leaks 2026-07-08"). Uncertainty-branched pushback +
+# anti-submission dynamics + persona-vs-artifact, aligned verbatim with
+# constitution rules `arkaos-not-yes-man` and `persona-vs-artifact`.
+_DISAGREEMENT_BLOCK = """\
+## Disagreement and escalation
+
+- Branch by epistemic state: confident the other side is wrong → push
+  back once with evidence, acknowledging you could be wrong; uncertain →
+  say so explicitly instead of capitulating or bluffing; asked to assert
+  something false → decline.
+- Insistence is not new evidence. Do not become more agreeable,
+  apologetic, or self-abasing as pressure rises; only NEW information
+  changes your position (that is updating, not caving).
+- Exit condition: after your objection is on record, if the decision
+  holder directs execution anyway, execute under explicit objection
+  ("executing under objection: <one-line reason>") — never sulk, never
+  sandbag.{escalation_line}"""
+
+_DELIVERABLE_BLOCK = """\
+## Deliverables
+
+- Your persona lives in the conversation, never in the deliverable:
+  client- or user-facing artifacts follow the style the context and the
+  client's brand demand (constitution `persona-vs-artifact`).
+- Never meta-reference your own persona or profile ("as a <type>,
+  I...") — the persona shows in behavior, it is not announced.
+- Never claim an action happened without the tool call on record; gates
+  pass on evidence, not narration (`evidence-flow`)."""
+
+
+def load_agent_yaml(path: Path) -> dict:
+    """Load one agent YAML; raises on unparseable/absent file."""
+    data = yaml.safe_load(path.read_text(encoding="utf-8"))
+    if not isinstance(data, dict):
+        raise ValueError(f"{path}: agent YAML did not parse to a mapping")
+    return data
+
+
+def _frontmatter(slug: str, data: dict) -> str:
+    role = data.get("role", slug)
+    dept = data.get("department", "")
+    domains = ", ".join((data.get("expertise") or {}).get("domains", [])[:4])
+    desc = f"{data.get('name', slug)} — {role} ({dept} squad)."
+    if domains:
+        desc += f" Executes: {domains}."
+    model = data.get("model", "sonnet")
+    return (
+        f"---\nname: {slug}\ndescription: >\n  {desc}\nmodel: {model}\n---"
+    )
+
+
+def _identity(data: dict) -> str:
+    dna = data.get("behavioral_dna") or {}
+    enn = dna.get("enneagram") or {}
+    name, role = data.get("name", "?"), data.get("role", "?")
+    dept, tier = data.get("department", "?"), data.get("tier", "?")
+    lines = [f"You are {name}, {role} of the {dept} squad (Tier {tier})."]
+    if enn.get("core_motivation"):
+        lines.append(f"What drives you: {enn['core_motivation']}.")
+    if enn.get("core_fear"):
+        lines.append(f"The failure you exist to prevent: {enn['core_fear']}.")
+    return " ".join(lines)
+
+
+def _work_rules(data: dict) -> list[str]:
+    # Label form throughout (QG B1/B2): DISC/communication fields are
+    # 3rd-person descriptors, not verb complements — gluing them to an
+    # imperative produced ungrammatical prompts in 8/8 pilot files.
+    dna = data.get("behavioral_dna") or {}
+    disc = dna.get("disc") or {}
+    comm = data.get("communication") or {}
+    rules: list[str] = []
+    if disc.get("communication_style"):
+        rules.append(f"Communication: {disc['communication_style']}.")
+    if comm.get("tone"):
+        rules.append(f"Tone: {comm['tone']}.")
+    if comm.get("preferred_format"):
+        rules.append(f"Default output shape: {comm['preferred_format']}.")
+    if disc.get("under_pressure"):
+        rules.append(f"Under pressure: {_lc(disc['under_pressure'])}.")
+    for item in comm.get("avoid", []):
+        rules.append(f"Avoid {item}.")
+    return rules
+
+
+def _lc(text: str) -> str:
+    return text[0].lower() + text[1:] if text else text
+
+
+def build_escalation_index(base: Path) -> dict[str, str]:
+    """Map every agent YAML id to a rendered escalation target.
+
+    Deployed subagents (pilot slugs + hand-written) render as a backtick
+    handle; everyone else renders by role and name — a handle that
+    resolves to no deployed subagent is worse than no handle (QG B3).
+    """
+    deployed = {out.stem for _, out in pilot_targets(base)} | _HAND_WRITTEN
+    slug_alias = {"tech-lead": "paulo-tech-lead"}
+    index: dict[str, str] = {}
+    for yaml_path in sorted(base.glob("departments/*/agents/*.yaml")):
+        try:
+            data = yaml.safe_load(yaml_path.read_text(encoding="utf-8"))
+        except Exception:
+            continue
+        if not isinstance(data, dict) or not data.get("id"):
+            continue
+        slug = slug_alias.get(yaml_path.stem, yaml_path.stem)
+        if slug in deployed:
+            index[data["id"]] = f"`{slug}`"
+        else:
+            role = data.get("role", yaml_path.stem)
+            name = data.get("name", "")
+            index[data["id"]] = f"the {role}" + (f" ({name})" if name else "")
+    return index
+
+
+def _blacklist(data: dict) -> list[str]:
+    markers = data.get("signature_markers") or {}
+    seen: list[str] = []
+    for phrase in markers.get("avoid_patterns", []):
+        if phrase not in seen:
+            seen.append(phrase)
+    return seen
+
+
+def _grounding(data: dict) -> str:
+    exp = data.get("expertise") or {}
+    models = data.get("mental_models") or {}
+    frameworks = list(exp.get("frameworks", [])) or list(
+        models.get("primary", [])
+    )
+    if not frameworks:
+        return ""
+    joined = ", ".join(frameworks)
+    return (
+        "## Grounding\n\nRecommendations cite the framework behind them — "
+        f"yours: {joined}. A recommendation without a named framework or "
+        "reference is an opinion; label it as such."
+    )
+
+
+def compile_agent(
+    data: dict,
+    slug: str,
+    yaml_rel_path: str,
+    escalation_index: dict[str, str] | None = None,
+) -> str:
+    """Compile one agent YAML dict into runtime subagent markdown."""
+    esc = (data.get("authority") or {}).get("escalates_to")
+    target = (escalation_index or {}).get(esc, esc) if esc else None
+    escalation_line = (
+        f"\n- Scope exceeded or deadlock after objection: escalate to "
+        f"{target}." if target else ""
+    )
+    sections = [
+        _frontmatter(slug, data),
+        f"<!-- generated by core/agents/behavioral_compiler.py from "
+        f"{yaml_rel_path} — DO NOT EDIT; edit the YAML and re-run -->",
+        f"# {data.get('name', slug)} — {data.get('role', slug)}",
+        _identity(data),
+    ]
+    work_rules = _work_rules(data)
+    if work_rules:
+        sections.append(
+            "## How you work\n\n" + "\n".join(f"- {r}" for r in work_rules)
+        )
+    blacklist = _blacklist(data)
+    if blacklist:
+        sections.append(
+            "## Never write\n\nThese exact phrases (any casing) are "
+            "banned from your output:\n"
+            + "\n".join(f'- "{p}"' for p in blacklist)
+        )
+    sections.append(_DISAGREEMENT_BLOCK.format(escalation_line=escalation_line))
+    sections.append(_DELIVERABLE_BLOCK)
+    grounding = _grounding(data)
+    if grounding:
+        sections.append(grounding)
+    return "\n\n".join(s for s in sections if s) + "\n"
+
+
+def pilot_targets(root: Path | None = None) -> list[tuple[Path, Path]]:
+    """(yaml_path, output_path) pairs for the pilot scope."""
+    base = root or _ROOT
+    pairs: list[tuple[Path, Path]] = []
+    for rel in _PILOT_YAMLS:
+        yaml_path = base / rel
+        slug = yaml_path.stem
+        if slug in _HAND_WRITTEN:
+            continue
+        pairs.append((yaml_path, base / "config" / "claude-agents" / f"{slug}.md"))
+    return pairs
+
+
+def check(root: Path | None = None) -> list[str]:
+    """Return drift messages (committed output != compiled YAML)."""
+    base = root or _ROOT
+    index = build_escalation_index(base)
+    problems: list[str] = []
+    for yaml_path, out_path in pilot_targets(base):
+        expected = compile_agent(
+            load_agent_yaml(yaml_path), out_path.stem,
+            str(yaml_path.relative_to(base)), index,
+        )
+        if not out_path.exists():
+            problems.append(f"{out_path}: missing — run --write")
+        elif out_path.read_text(encoding="utf-8") != expected:
+            problems.append(
+                f"{out_path}: drifted from {yaml_path.name} — run --write"
+            )
+    return problems
+
+
+def write(root: Path | None = None) -> list[Path]:
+    """(Re)generate every pilot agent; returns written paths."""
+    base = root or _ROOT
+    index = build_escalation_index(base)
+    written: list[Path] = []
+    for yaml_path, out_path in pilot_targets(base):
+        content = compile_agent(
+            load_agent_yaml(yaml_path), out_path.stem,
+            str(yaml_path.relative_to(base)), index,
+        )
+        out_path.write_text(content, encoding="utf-8")
+        written.append(out_path)
+    return written
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = argv if argv is not None else sys.argv[1:]
+    if "--write" in args:
+        for path in write():
+            print(f"wrote {path}")
+        return 0
+    problems = check()
+    for problem in problems:
+        print(problem)
+    print("behavioral-compiler: " + ("drift" if problems else "clean"))
+    return 1 if problems else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/core/governance/closing_marker_check.py

@@ -31,8 +31,8 @@ _TRIVIAL_WORD_THRESHOLD: int = 15
 _SUGGESTION_TEXT: str = (
     "Closing marker missing — end every flow-required turn with "
     "`[arka:gate:4] <label>` (evidence flow review gate) or "
-    "`[arka:trivial] <reason>` (single-file edit < 10 lines, "
-    "imperative verb). Without the marker, telemetry can't confirm "
+    "`[arka:trivial] <reason>` (single-file edit under 10 lines). "
+    "Without the marker, telemetry can't confirm "
     "the turn closed cleanly."
 )
 

package/core/governance/phantom_action_check.py

@@ -0,0 +1,221 @@
+"""Phantom-action soft-block (prompt-surface P0 2026-07-08).
+
+Response-side classifier. A "phantom action" is prose in the closing
+assistant message claiming a completed EFFECT ("criei o ficheiro X",
+"fiz commit", "I pushed the fix") in a turn that contains ZERO tool_use
+blocks — narrated work without a tool call on record is the grammatical
+form of delivery-theatre the ``evidence-flow`` rule bans. Pattern
+sourced from the 2026-07-08 prompt audit (Obsidian: "Projects/
+WizardingCode Internal/ArkaOS/Prompt Audit — system_prompts_leaks
+2026-07-08", finding "anti-phantom-action"; corpus clone at
+~/AIProjects/system_prompts_leaks).
+
+Precision-first: only claims whose completion implies a tool effect are
+flagged. Ambiguous verbs ("escrevi", "wrote", "corri", "ran") count only
+when bound to a concrete effect object (file, commit, tests, module…) —
+"escrevi um resumo abaixo" is response prose, not an effect claim.
+
+Mirrors the contract of ``core.governance.closing_marker_check``:
+soft-block, never raises on any input, hooks consume the result and log
+warn-only telemetry before any promotion to hard enforcement.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from dataclasses import dataclass, field
+
+# Objects whose creation/modification implies a tool effect.
+_EFFECT_OBJECT = (
+    r"(?:\b(?:ficheiros?|files?|m[óo]dulos?|modules?|branch(?:es)?|commits?"
+    r"|PRs?|pull.requests?|scripts?|testes?|tests?|suites?|classes?"
+    r"|fun[çc][õo]es?|functions?|hooks?|configs?|pipelines?|migra[çc][õo]es?"
+    r"|migrations?|packages?|releases?|tags?|documentos?|documents?"
+    r"|p[áa]ginas?|pages?|componentes?|components?|endpoints?|comandos?"
+    r"|commands?|builds?)\b|\.[a-z]{2,4}\b|`[^`]+`)"
+)
+
+# Analytic/mental nouns: a verb whose nearest object is one of these is
+# narrating the RESPONSE, not a tool effect ("updated my understanding of
+# the file", "adicionei contexto sobre os testes") — the effect object
+# match must not cross them (QG condition on #255 before enforcement).
+_ANALYTIC_NOUN = (
+    r"\b(?:understanding|context|summary|notes?|thinking|thoughts?"
+    r"|takeaways?|impressions?|sense|grasp|view|idea|picture"
+    r"|mental\s+model|contexto|resumo|notas?|entendimento"
+    r"|perce[çc][ãa]o|an[áa]lise|analysis|ideia|vis[ãa]o|imagem"
+    r"|no[çc][ãa]o|perspe[ct]?tiva|opini[ãa]o|conhecimento|knowledge)\b"
+)
+_GAP = r"(?:(?!" + _ANALYTIC_NOUN + r")[^.\n!?]){0,60}?"
+
+# Verbs whose completion is unambiguous on its own (git/publish/install).
+_STANDALONE_PT = (
+    r"(?<!não )\b(instalei|publiquei|gravei|renomeei|implementei"
+    r"|fiz\s+(?:o\s+|um\s+)?(?:commit|push|merge|deploy|release|rebase"
+    r"|revert))\b"
+)
+_STANDALONE_EN = (
+    r"\bI(?:'ve| have)?\s+(?:just\s+)?(committed|pushed|merged|published"
+    r"|released|deployed|installed)\b"
+)
+# Ambiguous verbs — only a claim when bound to an effect object nearby,
+# without an analytic noun in between. "ran into"/"ran through" are
+# idioms, never executions.
+_BOUND_PT = (
+    r"(?<!não )\b(criei|escrevi|atualizei|editei|apaguei|removi|adicionei"
+    r"|movi|apliquei|corri|executei)\b" + _GAP + _EFFECT_OBJECT
+)
+_BOUND_EN = (
+    r"\bI(?:'ve| have)?\s+(?:just\s+)?(created|wrote|updated|deleted"
+    r"|added|moved|applied|renamed|ran(?!\s+(?:into|through|over|across))"
+    r"|executed)\b" + _GAP + _EFFECT_OBJECT
+)
+_PASSIVE = (
+    r"\b(commit|push|merge|deploy|release|PR)\s+(feito|criado|efetuado"
+    r"|realizado|concluído)\b"
+)
+
+_CLAIM_PATTERNS: tuple[re.Pattern[str], ...] = tuple(
+    re.compile(p, re.IGNORECASE)
+    for p in (_STANDALONE_PT, _STANDALONE_EN, _BOUND_PT, _BOUND_EN, _PASSIVE)
+)
+
+_SUGGESTION_TEXT: str = (
+    "Phantom action — the closing message narrates a completed effect but "
+    "the turn contains no tool call. Prose in the past tense describing an "
+    "action is only valid with the corresponding tool call on record "
+    "(evidence-flow: gates pass on evidence, never on narration)."
+)
+
+
+@dataclass(frozen=True)
+class PhantomActionResult:
+    """Verdict of a phantom-action check. Immutable; safe to log as JSON."""
+
+    passed: bool
+    reason: str
+    claims: list[str] = field(default_factory=list)
+    suggestion: str | None = None
+
+
+def find_action_claims(response_text: str) -> list[str]:
+    """Return the distinct completed-effect claims found in the text."""
+    text = response_text or ""
+    hits: list[str] = []
+    for pattern in _CLAIM_PATTERNS:
+        for match in pattern.finditer(text):
+            token = match.group(0).strip().lower()
+            if token not in hits:
+                hits.append(token)
+    return hits
+
+
+def count_turn_tool_uses(raw_transcript: str | None) -> int | None:
+    """Count tool_use blocks in the final assistant turn of a transcript.
+
+    The turn is every record after the last REAL user message (a user
+    record whose content is not exclusively tool_result blocks). Returns
+    None when no parseable records exist OR when no real user message is
+    found — callers must fail open on None.
+    """
+    if not raw_transcript:
+        return None
+    records = _parse_jsonl(raw_transcript)
+    if not records:
+        return None
+    start = _last_real_user_index(records)
+    if start < 0:
+        return None
+    count = 0
+    for record in records[start + 1 :]:
+        if _record_role(record) != "assistant":
+            continue
+        count += _count_tool_use_blocks(record)
+    return count
+
+
+def check_phantom_actions(
+    response_text: str, raw_transcript: str | None
+) -> PhantomActionResult:
+    """Classify whether the closing message narrates unbacked effects.
+
+    Fail-open at every layer: an unparseable transcript skips the check,
+    and any unexpected error returns a passing "check-error" result — a
+    false PASS is telemetry noise, a false FAIL (or a crash) erodes
+    trust in the warn channel.
+    """
+    try:
+        claims = find_action_claims(response_text)
+        if not claims:
+            return PhantomActionResult(True, "no-claims")
+        tool_uses = count_turn_tool_uses(raw_transcript)
+        if tool_uses is None:
+            return PhantomActionResult(True, "transcript-unparseable", claims)
+        if tool_uses > 0:
+            return PhantomActionResult(True, "tools-present", claims)
+        return PhantomActionResult(
+            False, "phantom-action", claims, _SUGGESTION_TEXT
+        )
+    except Exception:
+        return PhantomActionResult(True, "check-error")
+
+
+def _parse_jsonl(raw: str) -> list[dict]:
+    records: list[dict] = []
+    for line in raw.splitlines():
+        if not line.strip():
+            continue
+        try:
+            record = json.loads(line)
+        except json.JSONDecodeError:
+            continue
+        if isinstance(record, dict):
+            records.append(record)
+    return records
+
+
+def _record_message(record: dict) -> dict:
+    message = record.get("message")
+    return message if isinstance(message, dict) else {}
+
+
+def _record_role(record: dict) -> str:
+    role = record.get("role") or _record_message(record).get("role")
+    return role if isinstance(role, str) else ""
+
+
+def _record_content(record: dict) -> object:
+    content = record.get("content")
+    if content is None:
+        content = _record_message(record).get("content")
+    return content
+
+
+def _last_real_user_index(records: list[dict]) -> int:
+    for idx in range(len(records) - 1, -1, -1):
+        if _record_role(records[idx]) != "user":
+            continue
+        content = _record_content(records[idx])
+        if isinstance(content, str):
+            return idx
+        if isinstance(content, list):
+            block_types = {
+                block.get("type")
+                for block in content
+                if isinstance(block, dict)
+            }
+            if block_types - {"tool_result"}:
+                return idx
+    return -1
+
+
+def _count_tool_use_blocks(record: dict) -> int:
+    content = _record_content(record)
+    if not isinstance(content, list):
+        return 0
+    return sum(
+        1
+        for block in content
+        if isinstance(block, dict) and block.get("type") == "tool_use"
+    )

package/core/governance/qg_verdict.py

@@ -28,6 +28,18 @@ class QGBlocker(BaseModel):
     file: str | None = Field(
         default=None, description="File (and line if known) of the issue"
     )
+    # Constitution 2.0 (PR-5, 2026-07-08): claim-level verdict vocabulary
+    # imported from the frontier review pattern — findings are judged
+    # individually, not only the deliverable as a whole.
+    verdict: Literal["CONFIRMED", "PLAUSIBLE", "REFUTED"] | None = Field(
+        default=None,
+        description=(
+            "Claim-level verdict after attempting reproduction: CONFIRMED "
+            "(reproduced from the code/output), PLAUSIBLE (credible but not "
+            "reproduced), REFUTED (disproven — recorded for telemetry, must "
+            "NOT count toward rejection)"
+        ),
+    )
 
 
 class QGEvidenceSummary(BaseModel):

package/core/hooks/stop.py

@@ -254,6 +254,28 @@ def _flow_checks(
     except Exception:
         pass
 
+    # Prompt-surface P0 2026-07-08 — phantom-action check (warn-only).
+    # Narrated effects without a tool call in the turn = the action did
+    # not happen (evidence-flow: evidence, never narration).
+    phantom_passed = True
+    phantom_reason = "no-claims"
+    phantom_claims: list = []
+    try:
+        from core.governance.phantom_action_check import check_phantom_actions
+        pr = check_phantom_actions(last, raw)
+        phantom_passed = pr.passed
+        phantom_reason = pr.reason
+        phantom_claims = pr.claims
+        if safe_sid:
+            _write_tmp_state("arkaos-phantom", safe_sid, {
+                "passed": pr.passed,
+                "reason": pr.reason,
+                "claims": pr.claims,
+                "suggestion": pr.suggestion,
+            })
+    except Exception:
+        pass
+
     entry = {
         "ts": datetime.now(timezone.utc).isoformat(),
         "session_id": session_id,
@@ -277,6 +299,9 @@ def _flow_checks(
         "kb_inflated": kb_inflated,
         "closing_marker_check_passed": closing_check_passed,
         "closing_marker_check_reason": closing_check_reason,
+        "phantom_check_passed": phantom_passed,
+        "phantom_check_reason": phantom_reason,
+        "phantom_claims": phantom_claims,
         "effort_level": effort_level,
         "mode": "warn",
     }