arkaos 3.73.1 → 3.74.0

package/VERSION

@@ -1 +1 @@
-3.73.1
+3.74.0

package/arka/skills/flow/SKILL.md

@@ -73,6 +73,16 @@ state the gap explicitly and propose filling it.
 Dispatch specialists via the `Agent` tool. The squad lead from Phase 3
 names them. Specialists run in parallel when work is independent.
 
+**Experience injection (PR3 v3.74.0).** When a specialist is dispatched,
+Synapse layer `L2.6 AgentExperiences`
+(`core/synapse/agent_experiences_layer.py`) detects the
+`[arka:dispatch] <from> -> <to>` marker and loads the top-5 most recent
+`Experience` records for the target agent from
+`~/.arkaos/agents/<agent_id>/experiences.jsonl`. The records list past
+Quality Gate REJECTED verdicts with their blockers and patterns. The
+dispatched specialist must read them and avoid repeating the failure
+modes. Operator-side audit: `python -m core.governance.agent_experiences_cli list <agent_id>`.
+
 **Dispatch must be announced (NON-NEGOTIABLE `dispatch-must-be-announced`).**
 Immediately before each `Agent` tool call, emit on its own line:
 
@@ -140,7 +150,13 @@ For each item, in order:
    injection, missing auth, data exposure.
    - Fail → back to the todo.
 5. **Quality Gate** — Marta (CQO) orchestrates the right specialists
-   for the area. If a specialist is missing, stop and advise the user
+   for the area. After Marta returns the verdict, the orchestrator MUST
+   call `core.governance.cqo_experience_recorder.record_from_verdict(...)`
+   when verdict is REJECTED (constitution rule `agent-experience-persistence`,
+   MUST level — PR3 v3.74.0). The recorder parses the blockers and writes
+   one Experience to the failing agent's log so the lesson is visible on
+   the next dispatch via the L2.6 Synapse layer. If a specialist is
+   missing, stop and advise the user
    to create one via `/arka personas` + provide the knowledge.
    - Fail → back to the todo.
 6. Document — save the completed work to Obsidian + vector DB.

package/config/constitution.yaml

@@ -193,6 +193,11 @@ enforcement_levels:
         rule: "Dispatch subagents only when task requires >3 Reads or >5 Greps or isolated context. Never parallel subagents sharing state. Prefer main thread for trivial tasks."
         enforcement: "warning"
 
+      # ─── Rule added in PR3 Squad Intelligence Upgrade (2026-05-28) ───────
+      - id: agent-experience-persistence
+        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 python -m core.governance.agent_experiences_cli list <agent_id>."
+
   should:
     description: "Best practices. Encouraged but not enforced."
     rules:

package/core/governance/agent_experiences.py

@@ -0,0 +1,176 @@
+"""Agent experience persistence — Quality Gate feedback loop store.
+
+When Marta (CQO) rejects an agent's work, an `Experience` record is
+appended to `~/.arkaos/agents/<agent_id>/experiences.jsonl`. The next
+time that agent is dispatched, recent experiences are injected as
+context so the agent inherits prior failures across sessions.
+
+This closes the long-standing QG learning gap: rejection reports used
+to live only in the PR thread; the agent that failed had no way to
+recall the structural mistake on the next pass. The Paulo of next
+month now sees what the Paulo of today learned the hard way.
+
+PR3 of the Squad Intelligence Upgrade.
+"""
+
+from __future__ import annotations
+
+import json
+from contextlib import contextmanager
+from dataclasses import asdict, dataclass, field
+from datetime import datetime
+from pathlib import Path
+
+from core.shared import safe_session_id as _safe_session_id_module
+
+try:
+    import fcntl  # POSIX only
+    _HAS_FLOCK = True
+except ImportError:
+    _HAS_FLOCK = False
+
+
+AGENTS_ROOT: Path = Path.home() / ".arkaos" / "agents"
+
+
+@dataclass
+class Experience:
+    """One QG verdict (or other lesson) captured for an agent.
+
+    `patterns` is a list (not a single string) because a verdict can fail
+    on multiple structural issues at once — e.g. function-length AND
+    governance-gap. PR3 v3.74.0 changed from `pattern: str | None` to
+    `patterns: list[str]` after Marta's QG-B6 ruled first-match-wins was
+    masking secondary patterns.
+    """
+
+    ts: str
+    agent_id: str
+    session_id: str
+    context: str
+    verdict: str
+    blockers: list[str] = field(default_factory=list)
+    patterns: list[str] = field(default_factory=list)
+    fix_applied: str | None = None
+    references: list[str] = field(default_factory=list)
+    tags: list[str] = field(default_factory=list)
+
+
+def experience_to_dict(exp: Experience) -> dict:
+    """Public serialiser for callers that need to persist outside this store."""
+    return asdict(exp)
+
+
+@contextmanager
+def _locked_append(path: Path):
+    """Append to `path` under POSIX flock; Windows falls back to O_APPEND atomicity."""
+    path.parent.mkdir(parents=True, exist_ok=True)
+    fh = path.open("a", encoding="utf-8")
+    try:
+        if _HAS_FLOCK:
+            fcntl.flock(fh.fileno(), fcntl.LOCK_EX)
+        yield fh
+    finally:
+        if _HAS_FLOCK:
+            try:
+                fcntl.flock(fh.fileno(), fcntl.LOCK_UN)
+            except OSError:
+                pass
+        fh.close()
+
+
+def _safe_agent_id(agent_id: str) -> str | None:
+    """Apply the same allowlist as session IDs (CWE-22 path-traversal guard)."""
+    return _safe_session_id_module.safe_session_id(agent_id)
+
+
+def _path_for(agent_id: str) -> Path | None:
+    safe = _safe_agent_id(agent_id)
+    if safe is None:
+        return None
+    return AGENTS_ROOT / safe / "experiences.jsonl"
+
+
+def record_experience(experience: Experience) -> None:
+    """Append an experience to the agent's JSONL.
+
+    Silently drops the record when the agent_id fails the safe-id check
+    or when filesystem I/O fails — recording must never block whatever
+    triggered the QG verdict.
+    """
+    path = _path_for(experience.agent_id)
+    if path is None:
+        return
+    try:
+        with _locked_append(path) as fh:
+            fh.write(json.dumps(asdict(experience)) + "\n")
+    except OSError:
+        return
+
+
+def _parse_entry(line: str) -> Experience | None:
+    """Decode one JSONL line into an Experience, or return None on bad input."""
+    try:
+        data = json.loads(line)
+    except json.JSONDecodeError:
+        return None
+    try:
+        return Experience(**data)
+    except (TypeError, ValueError):
+        return None
+
+
+def _filter_entry(
+    exp: Experience, since: datetime | None, tag: str | None
+) -> bool:
+    """Return True if the entry passes both filters."""
+    if since is not None:
+        try:
+            ts = datetime.fromisoformat(exp.ts)
+        except (TypeError, ValueError):
+            return False
+        if ts < since:
+            return False
+    if tag is not None and tag not in (exp.tags or []):
+        return False
+    return True
+
+
+def _read_entries(
+    path: Path, since: datetime | None, tag: str | None
+) -> list[Experience]:
+    """Parse the JSONL and apply filters. Empty on I/O error."""
+    entries: list[Experience] = []
+    try:
+        with path.open(encoding="utf-8") as fh:
+            for line in fh:
+                if not line.strip():
+                    continue
+                exp = _parse_entry(line)
+                if exp is None:
+                    continue
+                if _filter_entry(exp, since, tag):
+                    entries.append(exp)
+    except OSError:
+        return []
+    return entries
+
+
+def query_experiences(
+    agent_id: str,
+    *,
+    limit: int = 5,
+    since: datetime | None = None,
+    tag: str | None = None,
+) -> list[Experience]:
+    """Read experiences for an agent. Most recent first.
+
+    Empty list when the agent has no record or the agent_id is unsafe.
+    Malformed JSONL lines are skipped silently.
+    """
+    path = _path_for(agent_id)
+    if path is None or not path.exists():
+        return []
+    entries = _read_entries(path, since, tag)
+    entries.sort(key=lambda e: e.ts, reverse=True)
+    return entries[:limit]

package/core/governance/agent_experiences_cli.py

@@ -0,0 +1,98 @@
+"""CLI viewer for agent experiences.
+
+Usage:
+    python -m core.governance.agent_experiences_cli list <agent_id> [options]
+
+Options:
+    --limit N        Show at most N most-recent experiences (default 10)
+    --since DATE     ISO date or datetime (e.g. 2026-05-01)
+    --tag TAG        Show only entries with this tag
+
+Examples:
+    python -m core.governance.agent_experiences_cli list tech-lead-paulo
+    python -m core.governance.agent_experiences_cli list cqo-marta --limit 5
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from datetime import datetime
+
+from core.governance.agent_experiences import query_experiences
+
+
+def _format_experience(exp, index: int) -> str:
+    lines = [
+        f"  [{index}] {exp.ts}  {exp.verdict}  {exp.context}",
+    ]
+    if exp.patterns:
+        lines.append(f"        patterns: {', '.join(exp.patterns)}")
+    for blocker in (exp.blockers or [])[:5]:
+        lines.append(f"        - {blocker}")
+    if exp.fix_applied:
+        lines.append(f"        fix: {exp.fix_applied}")
+    if exp.references:
+        refs = ", ".join(exp.references[:3])
+        lines.append(f"        refs: {refs}")
+    if exp.tags:
+        lines.append(f"        tags: {', '.join(exp.tags)}")
+    return "\n".join(lines)
+
+
+def _parse_since(value: str) -> datetime:
+    """Accept either an ISO date (YYYY-MM-DD) or full ISO datetime."""
+    for fmt in ("%Y-%m-%dT%H:%M:%S%z", "%Y-%m-%dT%H:%M:%S", "%Y-%m-%d"):
+        try:
+            return datetime.strptime(value, fmt)
+        except ValueError:
+            continue
+    try:
+        return datetime.fromisoformat(value)
+    except ValueError as exc:
+        raise SystemExit(f"error: invalid --since value: {value}") from exc
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="python -m core.governance.agent_experiences_cli",
+        description="Inspect Quality Gate experience records for an agent.",
+    )
+    subparsers = parser.add_subparsers(dest="cmd", required=True)
+    list_p = subparsers.add_parser("list", help="List experiences for an agent.")
+    list_p.add_argument("agent_id", help="Agent ID, e.g. tech-lead-paulo")
+    list_p.add_argument("--limit", type=int, default=10, help="Max records (default 10)")
+    list_p.add_argument("--since", default=None, help="ISO date or datetime cutoff")
+    list_p.add_argument("--tag", default=None, help="Filter by tag")
+    return parser
+
+
+def _print_results(agent_id: str, experiences: list) -> int:
+    if not experiences:
+        print(f"No experiences recorded for {agent_id}.")
+        return 0
+    print(
+        f"Experiences for {agent_id} "
+        f"({len(experiences)} record(s), most recent first):\n"
+    )
+    for i, exp in enumerate(experiences, start=1):
+        print(_format_experience(exp, i))
+        print()
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = _build_parser()
+    args = parser.parse_args(argv if argv is not None else sys.argv[1:])
+    if args.cmd != "list":
+        parser.print_help()
+        return 2
+    since = _parse_since(args.since) if args.since else None
+    experiences = query_experiences(
+        args.agent_id, limit=args.limit, since=since, tag=args.tag
+    )
+    return _print_results(args.agent_id, experiences)
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())

package/core/governance/cqo_experience_recorder.py

@@ -0,0 +1,172 @@
+"""Parse Marta (CQO) verdict text and persist Experience records.
+
+When the orchestrator dispatches the `cqo` subagent for a Quality Gate
+review, Marta returns a verdict in a stable format (`Quality Gate
+Verdict: APPROVED|REJECTED`, with blockers labelled `B1.`, `B2.`,
+`M1.`, ...). This module parses that text and, when the verdict is
+REJECTED, appends an `Experience` to the failing agent's log so future
+dispatches inherit the lesson.
+
+For PR3 v1 the recorder is invoked manually by the orchestrator after a
+CQO dispatch. A future PR can wire it into a PostToolUse hook on the
+`Agent` tool so the persistence happens automatically.
+
+PR3 of the Squad Intelligence Upgrade.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from datetime import datetime, timezone
+
+from core.governance.agent_experiences import (
+    Experience,
+    record_experience,
+)
+
+
+_VERDICT_RE = re.compile(
+    r"Quality Gate Verdict:\s*(APPROVED|REJECTED)", re.IGNORECASE
+)
+
+# Blocker headings used by Marta across the codebase. Examples observed:
+# `**B1.` `**B2.` `**M1.` (markdown bold + dot/colon)
+# `B1.` `B1:` (plain)
+# `B1 description` (space-only separator — PR3 v3.74.0 widened per QG B5)
+# `B10.` `B11.` (double-digit labels)
+#
+# Documented limitation: inline blocker references mid-paragraph
+# (e.g., "The reviewer noted B1. is problematic") are NOT extracted —
+# only line-anchored labels qualify. This is intentional to keep
+# false-positive rate low; if we ever need inline capture, add a
+# separate pass with a stricter context check.
+_BLOCKER_RE = re.compile(
+    r"^(?:\*\*)?\s*([BMN])(\d+)[\s\.:](?:\s*\*\*)?\s*(.+?)(?:\*\*)?$",
+    re.MULTILINE,
+)
+
+# Common pattern hints Marta surfaces. Order matters — first match wins.
+_PATTERN_HINTS: tuple[tuple[str, str], ...] = (
+    (r"function length|line ceiling|\d+\s+lines?|exceeds.*line", "function-length-violation"),
+    (r"command[ -]injection|CWE-77|shell escape", "command-injection-risk"),
+    (r"path[ -]traversal|CWE-22", "path-traversal-risk"),
+    (r"undocumented|missing.*constitution|not in flow", "governance-gap"),
+    (r"missing.*test|zero.*coverage|no pytest", "test-coverage-gap"),
+    (r"workaround|hack|shortcut|TODO", "shortcut-applied"),
+    (r"client name|leak|confidential", "confidentiality-risk"),
+    (r"sycophancy|yes[- ]man|capitulat", "sycophancy-violation"),
+)
+
+
+@dataclass
+class ParsedVerdict:
+    """Structured view of a Marta verdict string."""
+
+    verdict: str  # "APPROVED" | "REJECTED" | "UNKNOWN"
+    blockers: list[str]
+    patterns: list[str]
+
+
+def parse_cqo_verdict(text: str) -> ParsedVerdict:
+    """Extract verdict, blocker list, and ALL matching pattern hints."""
+    if not text:
+        return ParsedVerdict(verdict="UNKNOWN", blockers=[], patterns=[])
+    verdict = _extract_verdict(text)
+    blockers = _extract_blockers(text) if verdict == "REJECTED" else []
+    patterns = _classify_patterns(text) if verdict == "REJECTED" else []
+    return ParsedVerdict(verdict=verdict, blockers=blockers, patterns=patterns)
+
+
+def _extract_verdict(text: str) -> str:
+    match = _VERDICT_RE.search(text)
+    if not match:
+        return "UNKNOWN"
+    return match.group(1).upper()
+
+
+def _extract_blockers(text: str) -> list[str]:
+    """Capture lines that start with a blocker label (B/M/N + digits)."""
+    blockers: list[str] = []
+    for match in _BLOCKER_RE.finditer(text):
+        kind, num, headline = match.group(1), match.group(2), match.group(3)
+        # Strip markdown markers and trailing whitespace.
+        headline = headline.replace("**", "").strip()
+        # Cap headline length so a single misformatted line cannot dominate.
+        if len(headline) > 200:
+            headline = headline[:197] + "..."
+        blockers.append(f"{kind}{num}: {headline}")
+    return blockers
+
+
+def _classify_patterns(text: str) -> list[str]:
+    """Return ALL matching pattern labels, in registry order.
+
+    First-match-wins was masking secondary patterns (PR3 QG-B6): a
+    verdict citing both governance-gap and function-length would be
+    classified only as function-length, and the agent would miss the
+    structural lesson. Returning all matches lets the dispatched agent
+    see every category at once.
+    """
+    lowered = text.lower()
+    matched: list[str] = []
+    for pattern, label in _PATTERN_HINTS:
+        if re.search(pattern, lowered, re.IGNORECASE):
+            matched.append(label)
+    return matched
+
+
+def _build_experience(
+    parsed: "ParsedVerdict",
+    *,
+    agent_id: str,
+    session_id: str,
+    context: str,
+    references: list[str] | None,
+    tags: list[str] | None,
+    fix_applied: str | None,
+) -> Experience:
+    """Compose an Experience from a parsed REJECTED verdict + caller metadata."""
+    return Experience(
+        ts=datetime.now(timezone.utc).isoformat(),
+        agent_id=agent_id,
+        session_id=session_id,
+        context=context,
+        verdict="REJECTED",
+        blockers=parsed.blockers,
+        patterns=parsed.patterns,
+        fix_applied=fix_applied,
+        references=references or [],
+        tags=tags or [],
+    )
+
+
+def record_from_verdict(
+    *,
+    verdict_text: str,
+    agent_id: str,
+    session_id: str,
+    context: str,
+    references: list[str] | None = None,
+    tags: list[str] | None = None,
+    fix_applied: str | None = None,
+) -> Experience | None:
+    """Parse `verdict_text` and append one Experience to `agent_id`'s log.
+
+    Returns the persisted Experience, or None when the verdict is not
+    REJECTED (APPROVED + UNKNOWN are not lessons worth recording).
+    """
+    parsed = parse_cqo_verdict(verdict_text)
+    if parsed.verdict != "REJECTED":
+        return None
+    experience = _build_experience(
+        parsed,
+        agent_id=agent_id,
+        session_id=session_id,
+        context=context,
+        references=references,
+        tags=tags,
+        fix_applied=fix_applied,
+    )
+    record_experience(experience)
+    return experience

package/core/synapse/agent_experiences_layer.py

@@ -0,0 +1,117 @@
+"""Synapse layer L2.6 — Agent Experience injection.
+
+When the user prompt contains `[arka:dispatch] <from> -> <target>`, this
+layer queries `core.governance.agent_experiences` for the target agent's
+recent experiences (REJECTED verdicts, lessons captured by the QG loop)
+and injects them as context so the dispatched specialist inherits prior
+failures across sessions.
+
+Designed as a standalone `Layer` subclass — engine wiring happens in a
+follow-up release (v3.74.1). For PR3 v1, callers (the UserPromptSubmit
+hook, or a manual dispatch wrapper) invoke `compute()` directly.
+
+Cache TTL: 30s. The experience file is appended-to, not rewritten, so a
+short TTL keeps newly-recorded lessons visible to the immediately-next
+dispatch.
+"""
+
+from __future__ import annotations
+
+import re
+import time
+
+from core.governance.agent_experiences import Experience, query_experiences
+from core.synapse.layers import Layer, LayerResult, PromptContext
+
+
+# Mirror the parser in core.workflow.specialist_enforcer so we recognise
+# the same marker the operator (and the constitution rule
+# `dispatch-must-be-announced`) require for specialist dispatches.
+_DISPATCH_RE = re.compile(
+    r"\[arka:dispatch\]\s*[\w-]+\s*->\s*([\w-]+)", re.IGNORECASE
+)
+
+
+class AgentExperiencesLayer(Layer):
+    """L2.6 — inject recent experiences for the dispatched specialist."""
+
+    def __init__(self, limit: int = 5) -> None:
+        self._limit = limit
+
+    @property
+    def id(self) -> str:
+        return "L2.6"
+
+    @property
+    def name(self) -> str:
+        return "AgentExperiences"
+
+    @property
+    def cache_ttl(self) -> int:
+        return 30
+
+    @property
+    def priority(self) -> int:
+        return 25  # after AgentLayer (L2 prio 20), before KBContext (L2.5)
+
+    def compute(self, ctx: PromptContext) -> LayerResult:
+        start = time.time()
+        target = _extract_dispatch_target(ctx.user_input)
+        if target is None:
+            return self._empty_result(start)
+
+        experiences = query_experiences(target, limit=self._limit)
+        if not experiences:
+            return self._empty_result(start, tag=f"[agent-experiences:{target} none]")
+
+        content = format_experiences(target, experiences)
+        ms = int((time.time() - start) * 1000)
+        return LayerResult(
+            layer_id=self.id,
+            tag=f"[agent-experiences:{target} count:{len(experiences)}]",
+            content=content,
+            tokens_est=max(1, len(content) // 4),
+            compute_ms=ms,
+            cached=False,
+        )
+
+    def _empty_result(self, start: float, tag: str = "") -> LayerResult:
+        return LayerResult(
+            layer_id=self.id,
+            tag=tag,
+            content="",
+            tokens_est=0,
+            compute_ms=int((time.time() - start) * 1000),
+            cached=False,
+        )
+
+
+def _extract_dispatch_target(user_input: str) -> str | None:
+    """Return the agent id from the most recent `[arka:dispatch]` marker."""
+    if not user_input:
+        return None
+    matches = list(_DISPATCH_RE.finditer(user_input))
+    if not matches:
+        return None
+    return matches[-1].group(1).lower()
+
+
+def format_experiences(target: str, experiences: list[Experience]) -> str:
+    """Render a compact, model-readable summary of past lessons."""
+    lines = [f"Past lessons for {target} (most recent first):"]
+    for i, exp in enumerate(experiences, start=1):
+        verdict = exp.verdict or "?"
+        context = exp.context or "(no context)"
+        head = f"  {i}. [{verdict}] {context}"
+        if exp.patterns:
+            head += f" — patterns: {', '.join(exp.patterns)}"
+        lines.append(head)
+        for blocker in (exp.blockers or [])[:3]:
+            lines.append(f"     - {blocker}")
+        if exp.fix_applied:
+            lines.append(f"     fix: {exp.fix_applied}")
+        if exp.references:
+            refs = ", ".join(exp.references[:2])
+            lines.append(f"     refs: {refs}")
+    lines.append("Apply these lessons proactively. Do not repeat the rejected patterns.")
+    return "\n".join(lines)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arkaos",
-  "version": "3.73.1",
+  "version": "3.74.0",
   "description": "The Operating System for AI Agent Teams",
   "type": "module",
   "bin": {

package/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "arkaos-core"
-version = "3.73.1"
+version = "3.74.0"
 description = "Core engine for ArkaOS — The Operating System for AI Agent Teams"
 readme = "README.md"
 license = {text = "MIT"}