arkaos 4.43.0 → 4.45.0

package/THE-ARKAOS-GUIDE.md

@@ -1,6 +1,6 @@
 # The ArkaOS Guide
 
-> v4.43.0 — 89 agents, 17 departments, 332 skills, 297 commands, 18 ADRs.
+> v4.45.0 — 89 agents, 17 departments, 332 skills, 297 commands, 18 ADRs.
 > One file, everything you need to start. Generated by `scripts/guide_gen.py` — never hand-edited.
 
 ## What it is

package/VERSION

@@ -1 +1 @@
-4.43.0
+4.45.0

package/config/hooks/agent-provision.sh

@@ -2,11 +2,23 @@
 # ArkaOS PreToolUse hook for dynamic agent provisioning.
 # Intercepts Task tool calls: if subagent_type is not present in the
 # project's .claude/agents/, copies it from ArkaOS core when available,
-# or blocks with an approval-request message when the agent must be
-# created via `/platform-arka agent provision <name>`.
+# or surfaces an approval-request message WITHOUT blocking when the
+# agent is unknown. The set of valid subagent_types is not enumerable
+# here — runtime built-ins (general-purpose, statusline-setup, …)
+# change with Claude Code versions and plugins add their own — so any
+# blocking arm on "unknown" breaks legitimate dispatches (QG PR-B5 r1
+# reproduced exit 2 on general-purpose). Provision when we know the
+# name; stand aside when we don't.
 
 set -euo pipefail
 
+# No jq, no payload parse. .claude/rules/bash-hooks.md:11-12 prescribes
+# a python3 fallback for jq; this gate is OPTIONAL by design, so it
+# stands aside instead of paying a python spawn on every Task call —
+# and per the same rules file ("exit code 2 = block action", last
+# bullet), exiting 0 here can never break a dispatch.
+command -v jq >/dev/null 2>&1 || exit 0
+
 # ─── Shared Python resolver (exports ARKA_PY) ──────────────────────────
 # The resolver guards its own ARKA_PY assignment with `|| true`, so sourcing
 # is set -e-safe even on the last-resort fallback. The trailing `|| true`
@@ -49,7 +61,6 @@ if [ -z "$core_root" ]; then
 fi
 
 if [ -d "$core_root/departments" ]; then
-    mkdir -p "$project_agents_dir"
     set +e
     "$ARKA_PY" - "$core_root" "$subagent_type" "$target" <<'PY'
 import os, re, sys
@@ -105,7 +116,10 @@ if md_path is not None:
 
 content = "\n".join(parts) + "\n"
 
-# Atomic write: temp file in same dir, then os.replace.
+# Create the parent only on the arm that actually writes (a dispatch
+# of an unknown name must not scatter empty .claude/agents/ dirs), then
+# atomic write: temp file in same dir, then os.replace.
+target.parent.mkdir(parents=True, exist_ok=True)
 tmp = target.with_suffix(".md.tmp")
 tmp.write_text(content)
 os.replace(tmp, target)
@@ -128,15 +142,22 @@ PY
     esac
 fi
 
-# Agent not in project and not in core — surface an approval-request.
+# Agent not in project, and the core lookup either found nothing or
+# never ran. Say exactly which, and NEVER block: this name may be a
+# runtime built-in or a plugin agent this script cannot know about —
+# if it truly doesn't exist, the Task dispatch itself fails with the
+# runtime's own error.
+if [ -d "$core_root/departments" ]; then
+    core_note="no ArkaOS core agent of that name was found (core searched at: $core_root)"
+else
+    core_note="the ArkaOS core lookup did not run (no departments/ under: ${core_root:-<unset>})"
+fi
 cat >&2 <<MSG
-[arka:provision-needed] Agent '$subagent_type' is not installed in this
-project and does not exist in ArkaOS core. To create it, run:
-
-    /platform-arka agent provision $subagent_type
-
-This opens the Skill Architect flow which drafts the agent YAML with
-4-framework DNA, goes through Quality Gate, and commits to core before
-propagating to the project. Blocking dispatch until the agent exists.
+[arka:provision-needed] Agent '$subagent_type' is not in this project's
+.claude/agents/, and $core_note.
+If ArkaOS should provide this agent, create it at
+.claude/agents/$subagent_type.md, or run 'npx arkaos update' so ArkaOS
+core ships a definition this gate can copy.
+Runtime built-ins and plugin agents are unaffected — dispatch proceeds.
 MSG
-exit 2
+exit 0

package/config/output-styles/arkaos.md

@@ -32,7 +32,7 @@ You are operating as ArkaOS — the Operating System for AI Agent Teams. You orc
 ## 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."
+- When routing to a department, INVOKE its skill first — `Skill(arka-dev)`, `Skill(arka-brand)`, `Skill(arka-content)`, … — then announce `[arka:routing] <dept> -> <lead>`. Announcing without invoking is not routing: the department's workflows do not enter context until the tool call.
 - 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.

package/core/governance/aggregate_guard.py

@@ -391,12 +391,33 @@ def _digest_issues(
     return issues, notes
 
 
-def _ended_issues(session_id: str) -> list[str]:
-    """A stamped session is not a live quorum (PR-B4 session binding)."""
+def _ended_issues(session_id: str, artifact_names: list[str]) -> list[str]:
+    """A stamped session is not a live quorum (PR-B4 session binding).
+
+    M4 hardening (PR-B5): the stamp only outlaws records that PREDATE
+    it. A counted record captured strictly after the stamp's mtime
+    proves the hook boundary came back to life under this session id —
+    never observed on the dev machine, where the stamp shipped one
+    release earlier and the ledger held a single stamped session when
+    this was written; the refusal must not outlive its own evidence.
+    Ties and unreadable mtimes keep the refusal: equality cannot
+    distinguish before from after, and fail-closed is the guard's
+    resting state.
+    """
     from core.governance.reviewer_ledger import ENDED_NAME
 
-    if not (ledger_root() / session_id / ENDED_NAME).is_file():
+    session_dir = ledger_root() / session_id
+    stamp = session_dir / ENDED_NAME
+    if not stamp.is_file():
         return []
+    try:
+        newest = max(
+            (session_dir / name).stat().st_mtime for name in artifact_names
+        )
+        if newest > stamp.stat().st_mtime:
+            return []
+    except (OSError, ValueError):
+        pass  # no readable counted record newer than the stamp
     return [
         f"session {session_id} is marked ended (SessionEnd stamped its "
         "ledger) — a past session's reviewer records are not a reusable "
@@ -568,7 +589,9 @@ def check_aggregate(aggregate: dict, session_id: str) -> GuardResult:
             reviewers, [name for name, _ in counted]
         )
     verdicts = [(str(r.get("reviewer_id")), r["verdict"]) for _, r in counted]
-    reasons, warnings = _reasons(aggregate, verdicts, session_id)
+    reasons, warnings = _reasons(
+        aggregate, verdicts, session_id, [name for name, _ in counted]
+    )
     return GuardResult(
         ok=not reasons,
         reasons=reasons,
@@ -579,7 +602,10 @@ def check_aggregate(aggregate: dict, session_id: str) -> GuardResult:
 
 
 def _reasons(
-    aggregate: dict, verdicts: list[tuple[str, dict]], session_id: str
+    aggregate: dict,
+    verdicts: list[tuple[str, dict]],
+    session_id: str,
+    artifact_names: list[str],
 ) -> tuple[list[str], list[str]]:
     """Every refusal reason and warning for one aggregate.
 
@@ -594,7 +620,7 @@ def _reasons(
     """
     approved = _norm(aggregate.get("verdict")) == "approved"
     issues, notes = _digest_issues(aggregate, verdicts)
-    issues += _ended_issues(session_id)
+    issues += _ended_issues(session_id, artifact_names)
     reasons = (
         _verdict_reasons(aggregate, verdicts)
         + _blocker_reasons(aggregate, verdicts, approved)

package/core/governance/quality_api.py

@@ -8,26 +8,15 @@ Provides a simple programmatic interface for the Quality Gate system:
 """
 
 import json
+from datetime import UTC
 from pathlib import Path
 from typing import Any
 
 from core.governance.quality_router import (
-    QualityRouter,
-    ReviewAssignment,
-    ReviewerType,
     DeliverableType,
-    ReviewPriority,
-    route_deliverable,
-)
-from core.governance.review_workflow import (
-    ReviewWorkflowEngine,
-    ReviewWorkflow,
-    ReviewPhase,
-    Verdict,
-    ReviewerOpinion,
+    QualityRouter,
 )
 
-
 _STATE_DIR = Path.home() / ".arkaos" / "quality-gate"
 _QUEUE_FILE = _STATE_DIR / "queue.json"
 _WORKFLOWS_FILE = _STATE_DIR / "workflows.json"
@@ -147,6 +136,14 @@ def record_verdict(
 ) -> bool:
     """Record a reviewer's verdict for a submission.
 
+    .. deprecated:: 4.44.0 (PR-B5)
+        Writes an unguarded label: no ledger artifact, no digest, no
+        aggregate guard. Use ``core.evals.record_cli``: ``--kind qg``
+        passes ``aggregate_guard.check_aggregate``, which requires at
+        least two hook-captured reviewer artifacts in the session
+        ledger; ``--kind reviewer`` remains an unguarded label path —
+        its ledger cross-reference is provenance, not admission.
+
     Args:
         submission_id: ID of the submission
         reviewer: Agent ID of reviewer
@@ -157,8 +154,6 @@ def record_verdict(
     Returns:
         True if verdict recorded successfully
     """
-    reviewer_type = ReviewerType(reviewer) if reviewer in [r.value for r in ReviewerType] else None
-
     queue = _load_queue()
     for item in queue:
         if item["id"] == submission_id:
@@ -217,9 +212,9 @@ def clear_resolved(older_than_days: int = 7) -> int:
     Returns:
         Number of items removed
     """
-    from datetime import datetime, timedelta, timezone
+    from datetime import datetime, timedelta
 
-    cutoff = datetime.now(timezone.utc) - timedelta(days=older_than_days)
+    cutoff = datetime.now(UTC) - timedelta(days=older_than_days)
     queue = _load_queue()
     original_count = len(queue)
 
@@ -268,6 +263,7 @@ class QualityGateAPI:
         feedback: str = "",
         flagged_rules: list[str] | None = None,
     ) -> bool:
+        """Deprecated with the module function — see ``record_verdict``."""
         return record_verdict(submission_id, reviewer, verdict, feedback, flagged_rules)
 
     def list_pending(self, reviewer: str | None = None) -> list[dict]:

package/core/governance/review_workflow.py

@@ -1,5 +1,15 @@
 """Review Workflow Engine — structured review phases for Quality Gate.
 
+.. deprecated:: 4.44.0 (PR-B5)
+    This engine models review phases in memory and records verdicts
+    WITHOUT the reviewer ledger or the aggregate guard behind them —
+    nothing here proves a verdict was authored at the hook boundary.
+    The guarded path is ``core.evals.record_cli``: ``--kind qg`` passes
+    ``aggregate_guard.check_aggregate``, which requires hook-captured
+    reviewer artifacts in the session ledger. The module stays
+    importable because live tests pin its phase mechanics, but no new
+    caller should route verdicts through it.
+
 Phases:
 1. Submission — deliverable submitted for review
 2. Triage — initial assessment, assign reviewers
@@ -16,13 +26,17 @@ Verdicts:
 """
 
 import uuid
+from collections.abc import Callable
 from dataclasses import dataclass, field
-from datetime import datetime, timezone
+from datetime import UTC, datetime
 from enum import Enum
-from typing import Callable
 
 
-class ReviewPhase(str, Enum):
+# UP042 suppressed on the three enums below: switching to StrEnum changes
+# str(member) from "Verdict.APPROVED" to "APPROVED" — behaviour, not
+# style — and this module is deprecated (see the module docstring), not
+# being modernised.
+class ReviewPhase(str, Enum):  # noqa: UP042
     SUBMISSION = "submission"
     TRIAGE = "triage"
     REVIEW = "review"
@@ -31,14 +45,14 @@ class ReviewPhase(str, Enum):
     DELIVERY = "delivery"
 
 
-class Verdict(str, Enum):
+class Verdict(str, Enum):  # noqa: UP042
     APPROVED = "APPROVED"
     REJECTED = "REJECTED"
     REQUEST_CHANGES = "REQUEST_CHANGES"
     ESCALATE = "ESCALATE"
 
 
-class ReviewerOpinion(str, Enum):
+class ReviewerOpinion(str, Enum):  # noqa: UP042
     APPROVE = "APPROVE"
     REJECT = "REJECT"
     CHANGES = "REQUEST_CHANGES"
@@ -79,7 +93,7 @@ class ReviewWorkflow:
 
     def __post_init__(self):
         if not self.submitted_at:
-            self.submitted_at = datetime.now(timezone.utc).isoformat()
+            self.submitted_at = datetime.now(UTC).isoformat()
 
 
 @dataclass
@@ -156,7 +170,7 @@ class ReviewWorkflowEngine:
         self._announce_phase_start(ReviewPhase.TRIAGE, workflow_id)
 
         workflow.phase = ReviewPhase.TRIAGE
-        workflow.triage_at = datetime.now(timezone.utc).isoformat()
+        workflow.triage_at = datetime.now(UTC).isoformat()
 
         result = PhaseResult(
             phase=ReviewPhase.TRIAGE,
@@ -191,7 +205,7 @@ class ReviewWorkflowEngine:
         self._announce_phase_start(ReviewPhase.REVIEW, workflow_id)
 
         workflow.phase = ReviewPhase.REVIEW
-        workflow.review_started_at = datetime.now(timezone.utc).isoformat()
+        workflow.review_started_at = datetime.now(UTC).isoformat()
 
         result = PhaseResult(
             phase=ReviewPhase.REVIEW,
@@ -248,7 +262,7 @@ class ReviewWorkflowEngine:
             opinion=opinion,
             comments=comments,
             flagged_rules=flagged_rules or [],
-            voted_at=datetime.now(timezone.utc).isoformat(),
+            voted_at=datetime.now(UTC).isoformat(),
             evidence_overall=evidence_overall,
         )
         workflow.votes.append(vote)
@@ -279,7 +293,7 @@ class ReviewWorkflowEngine:
         self._announce_phase_start(ReviewPhase.DELIBERATION, workflow_id)
 
         workflow.phase = ReviewPhase.DELIBERATION
-        workflow.deliberation_at = datetime.now(timezone.utc).isoformat()
+        workflow.deliberation_at = datetime.now(UTC).isoformat()
 
         result = PhaseResult(
             phase=ReviewPhase.DELIBERATION,
@@ -331,7 +345,7 @@ class ReviewWorkflowEngine:
         workflow.phase = ReviewPhase.VERDICT
         workflow.verdict = verdict
         workflow.feedback = feedback
-        workflow.verdict_at = datetime.now(timezone.utc).isoformat()
+        workflow.verdict_at = datetime.now(UTC).isoformat()
 
         self._announce_verdict(verdict, workflow_id)
 
@@ -370,7 +384,7 @@ class ReviewWorkflowEngine:
             )
 
         workflow.phase = ReviewPhase.DELIVERY
-        workflow.delivered_at = datetime.now(timezone.utc).isoformat()
+        workflow.delivered_at = datetime.now(UTC).isoformat()
 
         result = PhaseResult(
             phase=ReviewPhase.DELIVERY,

package/core/hooks/session_start.py

@@ -76,6 +76,22 @@ _EVIDENCE_CONTRACT = (
     " 10 lines."
 )
 
+# PR-A4: routing was fulfilled in PROSE — the model announced the squad
+# and never invoked the Skill tool, so the department's workflows and
+# contracts never entered context (the label without the payload). This
+# contract defines fulfilment; enforcement stays with A5a/A5b,
+# telemetry-gated.
+_SKILL_ROUTING_CONTRACT = (
+    "\n\n[ARKA:SKILL-CONTRACT] Routing IS tool invocation. A department"
+    " route is fulfilled by calling the department's hub skill — e.g."
+    " Skill(arka-dev), Skill(arka-brand), Skill(arka-content) — BEFORE"
+    " substantive work; announcing the squad in prose without invoking"
+    " the skill is not routing; it is the label without the payload."
+    "\nNever derive a hub name by concatenation — [arka:skill-hint] tags"
+    " name the exact call to make. The [arka:trivial] bypass is"
+    " unchanged."
+)
+
 _META_TAG_CONTRACT = (
     "\n\n[ARKA:META-TAG] Every substantive response ends with a single line:"
     "\n  [arka:meta] kb=N research=X persona=Y gap=Z critic=W"
@@ -348,6 +364,7 @@ def build_context(cwd: str) -> str:
     """
     parts = [
         _EVIDENCE_CONTRACT,
+        _SKILL_ROUTING_CONTRACT,
         _META_TAG_CONTRACT,
         _authority_brief(cwd),
         _model_fabric(),

package/core/hooks/stop.py

@@ -371,6 +371,60 @@ def _flow_checks(
         clear_flow_required(session_id)
 
 
+def _qg_aggregate_verdict(session_id: str) -> bool | None:
+    """Verdict from the session's guard-accepted ``AGGREGATE.json``.
+
+    True/False when a readable aggregate for THIS session exists — the
+    aggregate only lands on disk through aggregate_guard (PR-B3), so it
+    is authoritative in both directions. None when absent, foreign or
+    unreadable: only then may the caller fall back to the telemetry log.
+    """
+    try:
+        from core.governance.reviewer_ledger import (
+            AGGREGATE_NAME,
+            _safe_id,
+            ledger_root,
+        )
+
+        if not _safe_id(session_id):
+            return None
+        rec = json.loads(
+            (ledger_root() / session_id / AGGREGATE_NAME).read_text(
+                encoding="utf-8"
+            )
+        )
+    except Exception:
+        return None
+    if not isinstance(rec, dict) or rec.get("session_id") != session_id:
+        return None
+    verdict = (rec.get("aggregate") or {}).get("verdict", "")
+    return str(verdict).upper() == "APPROVED"
+
+
+def _qg_telemetry_approved(session_id: str) -> bool:
+    """Legacy fallback: newest ``qg.jsonl`` record for this session.
+
+    Pre-B3 sessions have no aggregate, so its absence proves nothing;
+    the unguarded telemetry log then keeps its historical role.
+    """
+    qg_log = Path.home() / ".arkaos" / "telemetry" / "qg.jsonl"
+    if not qg_log.exists():
+        return False
+    try:
+        for line in reversed(qg_log.read_text(encoding="utf-8").splitlines()):
+            if not line.strip():
+                continue
+            try:
+                rec = json.loads(line)
+            except Exception:
+                continue
+            if rec.get("session_id") == session_id:
+                return rec.get("verdict", "").upper() == "APPROVED"
+    except Exception:
+        pass
+    return False
+
+
 def _auto_doc_enqueue(
     session_id: str, transcript_path: str, raw: str | None
 ) -> None:
@@ -389,27 +443,19 @@ def _auto_doc_enqueue(
     except Exception:
         last = ""
 
-    qg_approved = bool(re.search(r"\[arka:qg:approved\]", last, re.IGNORECASE))
-    if not qg_approved:
-        qg_log = Path.home() / ".arkaos" / "telemetry" / "qg.jsonl"
-        if qg_log.exists():
-            try:
-                for line in reversed(
-                    qg_log.read_text(encoding="utf-8").splitlines()
-                ):
-                    if not line.strip():
-                        continue
-                    try:
-                        rec = json.loads(line)
-                    except Exception:
-                        continue
-                    if rec.get("session_id") == session_id:
-                        qg_approved = (
-                            rec.get("verdict", "").upper() == "APPROVED"
-                        )
-                        break
-            except Exception:
-                pass
+    # The guard-accepted aggregate is authoritative either way (PR-B5,
+    # G7) — over the telemetry log AND over the assistant's own
+    # [arka:qg:approved] marker: narration must not outrank the record
+    # it narrates (the same laundering shape G7 closes one layer down).
+    # Marker and telemetry keep their historical roles only when no
+    # aggregate exists for the session.
+    from_aggregate = _qg_aggregate_verdict(session_id)
+    if from_aggregate is not None:
+        qg_approved = from_aggregate
+    else:
+        qg_approved = bool(
+            re.search(r"\[arka:qg:approved\]", last, re.IGNORECASE)
+        ) or _qg_telemetry_approved(session_id)
     if not qg_approved:
         return
 

package/core/runtime/opencode_hooks.py

@@ -31,7 +31,7 @@ import os
 import re
 import subprocess
 import sys
-from datetime import datetime, timezone
+from datetime import UTC, datetime
 from pathlib import Path
 
 _TELEMETRY_DIR = Path.home() / ".arkaos" / "telemetry"
@@ -135,7 +135,10 @@ def _load_commands_registry() -> list[dict]:
 
 def _routing_lines(prompt: str, session_id: str, cwd: str) -> list[str]:
     """UserPromptSubmit routing parity (core/hooks/user_prompt_submit.py):
-    [ARKA:ROUTE] on every prompt + L1 [dept:X] + L5 [hint:/cmd] +
+    [ARKA:ROUTE] on every prompt + L1 [dept:X] + L5 [arka:skill-hint]
+    Skill(<hub>) -> /cmd (PR-A4 imperative form; hub resolved by
+    layers._hub_skill, never by slug concatenation — a /mkt hint
+    renders Skill(arka-marketing)) +
     [ARKA:WORKFLOW-REQUIRED] on creation/implementation prompts. The
     directive strings and the verb regex are IMPORTED from the claude
     hook — one source of truth, zero drift."""
@@ -170,7 +173,7 @@ def _routing_lines(prompt: str, session_id: str, cwd: str) -> list[str]:
             hints = CommandHintsLayer(commands=commands).compute(ctx)
             if hints.tag:
                 lines.append(hints.tag)
-    except Exception:  # noqa: BLE001 — routing hints are a bonus, never a blocker
+    except Exception:
         pass
     if prompt[0] not in ("/", "!") and _WF_VERB_RE.search(prompt):
         lines.append(_WORKFLOW_DIRECTIVE.strip())
@@ -285,7 +288,7 @@ def _action_post_tool(payload: dict) -> dict:
     _append_jsonl(
         _TELEMETRY_DIR / "opencode-tools.jsonl",
         {
-            "ts": datetime.now(timezone.utc).isoformat(),
+            "ts": datetime.now(UTC).isoformat(),
             "session": session_id,
             "tool": mapped,
             "ok": bool(payload.get("ok", True)),
@@ -319,7 +322,7 @@ def _enqueue_turn_capture(session_id: str, text: str, cwd: str) -> None:
                 proc.stdin.close()
             except (BrokenPipeError, OSError):
                 pass
-    except Exception:  # noqa: BLE001 — a hook bridge never breaks a turn
+    except Exception:
         pass
 
 
@@ -347,7 +350,7 @@ def _action_idle(payload: dict) -> dict:
     _append_jsonl(
         _TELEMETRY_DIR / "opencode-compliance.jsonl",
         {
-            "ts": datetime.now(timezone.utc).isoformat(),
+            "ts": datetime.now(UTC).isoformat(),
             "session": session_id,
             "kb_cite": result.reason,
             "meta_tag": "[arka:meta]" in text,
@@ -388,7 +391,7 @@ def _handoff_line(session_id: str, project: str) -> str:
     try:
         _handoff_marker(session_id).parent.mkdir(parents=True, exist_ok=True)
         _handoff_marker(session_id).write_text(
-            json.dumps({"shown_at": datetime.now(timezone.utc).isoformat()}),
+            json.dumps({"shown_at": datetime.now(UTC).isoformat()}),
             encoding="utf-8",
         )
     except OSError:
@@ -440,7 +443,7 @@ def _action_memory(payload: dict) -> dict:
         handoff = _handoff_line(session_id, project)
         if handoff:
             lines.insert(0, handoff)
-    except Exception:  # noqa: BLE001 — memory is a bonus, never a blocker
+    except Exception:
         return {"context": []}
     return {"context": lines[:6]}
 
@@ -460,7 +463,7 @@ def _action_compact(payload: dict) -> dict:
         current = state.get_state()
         if current:
             context.append(f"Workflow activo: {json.dumps(current)[:400]}")
-    except Exception:  # noqa: BLE001 — fail-open
+    except Exception:
         pass
     return {"context": context}
 
@@ -488,7 +491,7 @@ def main() -> int:
     else:
         try:
             result = handler(payload)
-        except Exception as exc:  # noqa: BLE001 — fail-open, never block
+        except Exception as exc:
             result = {"error": f"{type(exc).__name__}: {exc}"}
     sys.stdout.write(json.dumps(result, ensure_ascii=False) + "\n")
     return 0