arkaos 4.21.0 → 4.22.0

package/README.md

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

package/VERSION

@@ -1 +1 @@
-4.21.0
+4.22.0

package/arka/SKILL.md

@@ -25,7 +25,7 @@ measures citation compliance per turn.
 # ArkaOS — Main Orchestrator
 
 > **The Operating System for AI Agent Teams**
-> 86 agents. 17 departments. 290 skills. Multi-runtime. Dashboard. Knowledge RAG.
+> 86 agents. 17 departments. 292 skills. Multi-runtime. Dashboard. Knowledge RAG.
 
 ## ⛔ Evidence flow — 4 gates (NON-NEGOTIABLE)
 
@@ -175,6 +175,7 @@ violation (squad-routing, arka-supremacy, spec-driven, mandatory-qa).
 | `/arka mcps [period]` | MCP usage — aggregates the PostToolUse MCP telemetry (`~/.arkaos/telemetry/mcp-usage.jsonl`) by day/week/month/all. Shows total calls, servers in use, top servers and top tools. Shells out to `~/.arkaos/bin/arka-py -m core.runtime.mcp_telemetry_cli <period>`. |
 | `/arka compliance [period]` | Behavior compliance summary (PR29 v2.48.0) — aggregates stop-hook telemetry by day/week/month/all. Shows rates for the four contracts: closing marker, `[arka:meta]` tag, KB citation pass, sycophancy clean. Shells out to `~/.arkaos/bin/arka-py -m core.governance.compliance_telemetry_cli <period>`. |
 | `/arka reorganize [--since-days N]` | Dreaming → Agent reorganizer. Aggregates recent KB pattern/anti-pattern/lesson artifacts (default last 7 days) into a markdown proposal at `~/.arkaos/reorganize-proposals/<date>.md`. **Propose-only** — never modifies agent YAMLs. Sanitizes client identifiers from titles and body excerpts; drops `tags:` field entirely to prevent project-name leaks. **Auto-fires on session start when today's proposal is missing** (PR24 v2.46.0 stale-aware trigger, 30s timeout, background). Shells out to `~/.arkaos/bin/arka-py -m core.cognition.reorganizer_cli [--since-days N] [--dry-run]`. |
+| `/arka evolve [--min-projects N] [--min-confidence X]` | Instinct evolution. Ingests accumulated cross-project signals (`~/.arkaos/gotchas.json`) into the InsightStore as deterministic instincts (confidence in the [0.3, 0.9] band from occurrence count) and writes a markdown proposal at `~/.arkaos/evolve-proposals/<date>.md` with cross-project promotion candidates (`InsightStore.promotable`) and the strongest instincts. **Propose-only** — nothing is promoted or modified; LLM-free (Dreaming owns vault clustering). Redacts client identifiers; never renders project names. Shells out to `~/.arkaos/bin/arka-py -m core.cognition.evolve_cli [--min-projects N] [--min-confidence X] [--dry-run]`. |
 | `/arka standup` | Daily standup (projects, priorities, blockers, updates) |
 | `/arka monitor` | System health monitoring |
 | `/arka onboard <path>` | Onboard an existing project into ArkaOS |

package/config/claude-agents/marta-cqo.md

@@ -41,6 +41,15 @@ evidence report, never from model size.
      justification in notes; otherwise REJECTED.
 4. Record the outcome via `core.governance.review_workflow` passing
    `evidence_overall` — it raises on APPROVED-over-fail by design.
+5. Record the eval label (evals ADR 2026-07-09) as your FINAL act — the
+   corpus only grows if the verdict-issuer writes it, and dispatch
+   through this agent bypasses the department SKILL's step 6: write your
+   final QGVerdict JSON to a temp file and run
+   `~/.arkaos/bin/arka-py -m core.evals.record_cli --file <f> --kind qg
+   --department <dept> --deliverable "<title>"`. It fails LOUDLY on
+   invalid JSON — if it fails, fix the JSON and re-run; never skip.
+   Every review feeds `~/.arkaos/telemetry/qg-verdicts.jsonl`, redo
+   verdicts included (a REJECTED→APPROVED pair is two labels).
 
 ## Verdict Format
 

package/config/standards/{claude-md-overlays → stack-rules}/laravel.md

@@ -1,3 +1,12 @@
+---
+paths:
+  - "app/**/*.php"
+  - "routes/**/*.php"
+  - "database/**/*.php"
+  - "config/**/*.php"
+  - "tests/**/*.php"
+---
+
 ## Laravel Stack Conventions
 
 - Services + Repositories pattern; no logic in controllers.
@@ -5,4 +14,6 @@
 - API Resources for response shaping.
 - Feature Tests with RefreshDatabase trait.
 - Eloquent relationships over raw joins.
+- Policies for authorization; never inline ability checks.
+- Queued jobs for slow work; never block the request cycle.
 - Conventional commits: `feat(scope): ...`, `fix(scope): ...`.

package/config/standards/{claude-md-overlays → stack-rules}/node.md

@@ -1,7 +1,16 @@
-## Node.js Stack Conventions
+---
+paths:
+  - "**/*.js"
+  - "**/*.mjs"
+  - "**/*.cjs"
+  - "**/*.ts"
+---
+
+## Node.js / JavaScript Stack Conventions
 
 - ESM modules (import/export); no CommonJS `require()`.
 - Support Node and Bun runtimes when writing CLI tooling.
 - Graceful fallbacks when optional dependencies are missing.
 - All paths via `os.homedir()` or `path.join`; never hardcoded.
 - No interactive prompts in headless/CI runs.
+- Prefer built-in `node:` modules over dependencies.

package/config/standards/{claude-md-overlays → stack-rules}/nuxt.md

@@ -1,8 +1,19 @@
-## Nuxt / Vue Stack Conventions
+---
+paths:
+  - "**/*.vue"
+  - "composables/**"
+  - "pages/**"
+  - "layouts/**"
+  - "server/**"
+  - "nuxt.config.*"
+---
+
+## Nuxt Stack Conventions
 
 - Composition API only; no Options API.
 - TypeScript everywhere; no plain JS Vue files.
 - `composables/` for shared reactive logic.
 - `useFetch`/`useAsyncData` for server-side data.
 - `~` alias for project root imports.
+- Server routes in `server/api/`; never fetch third parties from components.
 - Tailwind for styling; avoid scoped styles unless necessary.

package/config/standards/stack-rules/php.md

@@ -0,0 +1,13 @@
+---
+paths:
+  - "**/*.php"
+---
+
+## PHP Stack Conventions
+
+- PHP 8.2+ syntax: constructor promotion, readonly, enums, match.
+- `declare(strict_types=1)` in every file.
+- Typed properties, parameters, and return types everywhere.
+- Composer autoload (PSR-4); never `require` project files by path.
+- Exceptions over error returns; never `@` error suppression.
+- Pint (or the project formatter) must pass before a change is done.

package/config/standards/{claude-md-overlays → stack-rules}/python.md

@@ -1,3 +1,8 @@
+---
+paths:
+  - "**/*.py"
+---
+
 ## Python Stack Conventions
 
 - Type hints on every function signature.

package/config/standards/stack-rules/react.md

@@ -0,0 +1,14 @@
+---
+paths:
+  - "**/*.tsx"
+  - "**/*.jsx"
+---
+
+## React / Next.js Stack Conventions
+
+- TypeScript everywhere; no plain JSX files.
+- Server Components by default; `"use client"` only when interaction demands it.
+- App Router (`app/`); no new Pages Router code.
+- shadcn/ui + Tailwind for UI primitives.
+- Hooks for shared logic; no HOC or render-prop patterns in new code.
+- Co-locate component, styles, and test; PascalCase component files.

package/config/standards/stack-rules/vue.md

@@ -0,0 +1,13 @@
+---
+paths:
+  - "**/*.vue"
+---
+
+## Vue Stack Conventions
+
+- Composition API only; no Options API.
+- `<script setup lang="ts">` in every component.
+- Props and emits fully typed (`defineProps`/`defineEmits` generics).
+- Shared reactive logic lives in composables, not mixins.
+- One component per file; PascalCase filenames.
+- v-for always keyed; no index keys on mutable lists.

package/core/cognition/evolve.py

@@ -0,0 +1,299 @@
+"""Evolve — turn accumulated cross-project signals into instinct proposals.
+
+Propose-only, LLM-free. The engine ingests the raw signals sessions
+already accumulate (``~/.arkaos/gotchas.json`` — error patterns with
+occurrence counts and the projects they appeared in) into the
+``InsightStore`` as deterministic instincts: confidence derives from the
+occurrence count inside the [0.3, 0.9] band, evidence_count mirrors the
+raw count, and the record id is a stable digest of (source, title,
+project) so re-ingestion is idempotent. It then renders a markdown
+proposal at ``~/.arkaos/evolve-proposals/<date>.md`` with the
+cross-project promotion candidates (``InsightStore.promotable`` — this
+module is that API's first production caller) and the strongest
+instincts.
+
+Boundaries: Dreaming owns vault clustering (LLM, multi-backend) — evolve
+never re-clusters markdown; it consumes structured stores only. Nothing
+is promoted, modified, or deleted: the proposal file is the only output
+(the reorganizer contract). Client identifiers are redacted and
+project names are never rendered — only distinct-project counts.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import tempfile
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+from pathlib import Path
+
+from core.cognition.insights.store import InsightStore
+from core.cognition.memory.schemas import (
+    INSTINCT_CONFIDENCE_MAX,
+    INSTINCT_CONFIDENCE_MIN,
+    ActionableInsight,
+)
+from core.cognition.reorganizer import md_escape, redact_clients
+
+_DEFAULT_OUTPUT_DIR = Path.home() / ".arkaos" / "evolve-proposals"
+_DEFAULT_GOTCHAS_PATH = Path.home() / ".arkaos" / "gotchas.json"
+_DEFAULT_DB_PATH = Path.home() / ".arkaos" / "insights.db"
+_PROPOSAL_FILENAME_FMT = "%Y-%m-%d.md"
+_CONFIDENCE_STEP = 0.1
+_TOP_INSTINCTS = 10
+
+
+@dataclass(frozen=True)
+class PromotionCandidate:
+    """Cross-project instinct eligible for promotion (propose-only)."""
+
+    title: str
+    project_count: int
+    mean_confidence: float
+    evidence_count: int
+
+
+@dataclass(frozen=True)
+class EvolveReport:
+    """Evolve run outcome. Never contains client or project identifiers."""
+
+    date: str
+    ingested: int
+    pending_instincts: int
+    candidates: list[PromotionCandidate] = field(default_factory=list)
+    proposal_path: str | None = None
+
+
+def derive_confidence(count: int) -> float:
+    """Occurrence count -> confidence, deterministic, inside the band."""
+    raw = INSTINCT_CONFIDENCE_MIN + _CONFIDENCE_STEP * (max(1, count) - 1)
+    return min(INSTINCT_CONFIDENCE_MAX, raw)
+
+
+def _stable_id(source: str, title: str, project: str) -> str:
+    digest = hashlib.sha1(f"{source}:{title}:{project}".encode())
+    return digest.hexdigest()[:32]
+
+
+def _load_gotchas(gotchas_path: Path) -> list[dict]:
+    try:
+        data = json.loads(gotchas_path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return []
+    entries = data.get("gotchas") if isinstance(data, dict) else data
+    return [e for e in entries or [] if isinstance(e, dict)]
+
+
+def _instinct_from_gotcha(gotcha: dict, project: str) -> ActionableInsight | None:
+    title = str(gotcha.get("pattern") or "").strip()
+    if not title or not project.strip():
+        return None
+    count = int(gotcha.get("count") or 1)
+    return ActionableInsight(
+        id=_stable_id("gotcha", title, project),
+        project=project,
+        trigger="evolve-ingest",
+        category="technical",
+        severity="improve" if count >= 5 else "consider",
+        title=title,
+        description=str(gotcha.get("full_pattern") or title),
+        recommendation=str(gotcha.get("suggestion") or "").strip()
+        or "Recurring signal — consider a rule, skill, or fix.",
+        context=f"tool={gotcha.get('tool', '?')} count={count}",
+        confidence=derive_confidence(count),
+        evidence_count=max(1, count),
+    )
+
+
+def ingest_gotchas(store: InsightStore, gotchas_path: Path) -> int:
+    """Mirror gotcha signals into the store as project-scoped instincts.
+
+    Deterministic derivation from the source of truth: re-ingesting
+    recomputes the same ids and values (INSERT OR REPLACE), so repeat
+    runs are idempotent.
+    """
+    ingested = 0
+    for gotcha in _load_gotchas(gotchas_path):
+        projects = gotcha.get("projects") or []
+        for project in {str(p) for p in projects if str(p).strip()}:
+            insight = _instinct_from_gotcha(gotcha, project)
+            if insight is None:
+                continue
+            store.save(insight)
+            ingested += 1
+    return ingested
+
+
+def _candidates(
+    store: InsightStore, min_projects: int, min_confidence: float,
+) -> list[PromotionCandidate]:
+    titles = store.promotable(
+        min_projects=min_projects, min_confidence=min_confidence
+    )
+    rows = [i for i in store.get_all_pending() if i.scope == "project"]
+    out: list[PromotionCandidate] = []
+    for title in titles:
+        group = [i for i in rows if i.title == title]
+        if not group:
+            continue
+        out.append(
+            PromotionCandidate(
+                title=title,
+                project_count=len({i.project for i in group}),
+                mean_confidence=round(
+                    sum(i.confidence for i in group) / len(group), 2
+                ),
+                evidence_count=sum(i.evidence_count for i in group),
+            )
+        )
+    return out
+
+
+def build_proposal(
+    *,
+    db_path: Path | None = None,
+    gotchas_path: Path | None = None,
+    output_dir: Path | None = None,
+    dry_run: bool = False,
+    min_projects: int = 2,
+    min_confidence: float = 0.8,
+) -> EvolveReport:
+    """Ingest signals, compute promotion candidates, write the proposal."""
+    store = InsightStore(db_path or _DEFAULT_DB_PATH)
+    ingested = ingest_gotchas(store, gotchas_path or _DEFAULT_GOTCHAS_PATH)
+    pending = store.get_all_pending()
+    candidates = _candidates(store, min_projects, min_confidence)
+    date = datetime.now(UTC).strftime("%Y-%m-%d")
+    markdown = _render(date, ingested, pending, candidates)
+    if dry_run:
+        print(markdown)
+        return EvolveReport(date, ingested, len(pending), candidates)
+    path = _write_report(markdown, output_dir)
+    return EvolveReport(date, ingested, len(pending), candidates, str(path))
+
+
+def _render_candidate(candidate: PromotionCandidate) -> str:
+    title = md_escape(redact_clients(candidate.title))
+    return (
+        f"| {title} | {candidate.project_count} | "
+        f"{candidate.mean_confidence:.2f} | {candidate.evidence_count} |"
+    )
+
+
+def _render_instinct(insight: ActionableInsight) -> str:
+    title = md_escape(redact_clients(insight.title))
+    rec = md_escape(redact_clients(insight.recommendation))
+    return (
+        f"- **{title}** — confidence {insight.confidence:.2f}, "
+        f"evidence {insight.evidence_count}. {rec}"
+    )
+
+
+def _render_summary(
+    date: str, ingested: int, pending_count: int, candidate_count: int,
+) -> list[str]:
+    return [
+        f"# Evolve proposal — {date}",
+        "",
+        "> Propose-only: nothing was promoted or modified. Review and",
+        "> act via the squads; promotion stays a deliberate operator call.",
+        "",
+        "## Summary",
+        "",
+        f"- Instincts ingested this run: **{ingested}**",
+        f"- Pending instincts in store: **{pending_count}**",
+        f"- Promotion candidates: **{candidate_count}**",
+        "",
+    ]
+
+
+def _render_candidates_block(candidates: list[PromotionCandidate]) -> list[str]:
+    lines = ["## Promotion candidates (cross-project)", ""]
+    if candidates:
+        lines += [
+            "| Instinct | Projects | Mean confidence | Evidence |",
+            "|---|---|---|---|",
+            *[_render_candidate(c) for c in candidates],
+        ]
+    else:
+        lines.append("None yet — needs the same signal in 2+ projects.")
+    return lines
+
+
+def _strongest_by_title(pending: list[ActionableInsight]) -> list[ActionableInsight]:
+    """Top instincts, one row per title (a cross-project pattern has one
+    project-scoped row per project — the operator needs it once)."""
+    ranked = sorted(
+        pending, key=lambda i: (i.confidence, i.evidence_count), reverse=True
+    )
+    seen: set[str] = set()
+    out: list[ActionableInsight] = []
+    for insight in ranked:
+        if insight.title in seen:
+            continue
+        seen.add(insight.title)
+        out.append(insight)
+        if len(out) == _TOP_INSTINCTS:
+            break
+    return out
+
+
+def _render_instincts_block(pending: list[ActionableInsight]) -> list[str]:
+    strongest = _strongest_by_title(pending)
+    lines = ["", "## Strongest instincts", ""]
+    if strongest:
+        lines += [_render_instinct(i) for i in strongest]
+    else:
+        lines.append("Store is empty — no signals accumulated yet.")
+    return lines
+
+
+def _render(
+    date: str,
+    ingested: int,
+    pending: list[ActionableInsight],
+    candidates: list[PromotionCandidate],
+) -> str:
+    lines = (
+        _render_summary(date, ingested, len(pending), len(candidates))
+        + _render_candidates_block(candidates)
+        + _render_instincts_block(pending)
+    )
+    return "\n".join(lines) + "\n"
+
+
+def _write_report(markdown: str, output_dir: Path | None) -> Path:
+    """Atomic markdown write to an allowlisted output directory."""
+    out = _validate_output_dir(output_dir)
+    out.mkdir(parents=True, exist_ok=True)
+    report_path = out / datetime.now(UTC).strftime(
+        _PROPOSAL_FILENAME_FMT
+    )
+    tmp_path = report_path.with_suffix(f".tmp-{os.getpid()}.md")
+    tmp_path.write_text(markdown, encoding="utf-8")
+    os.replace(tmp_path, report_path)
+    return report_path
+
+
+def _validate_output_dir(output_dir: Path | None) -> Path:
+    """Allowlist writes to ~/.arkaos or the system tempdir (defence in
+    depth — same contract as the reorganizer)."""
+    if output_dir is None:
+        return _DEFAULT_OUTPUT_DIR
+    resolved = Path(output_dir).expanduser().resolve()
+    allowed_roots = (
+        (Path.home() / ".arkaos").resolve(),
+        Path(tempfile.gettempdir()).resolve(),
+    )
+    for root in allowed_roots:
+        try:
+            resolved.relative_to(root)
+            return resolved
+        except ValueError:
+            continue
+    raise ValueError(
+        "output_dir must be under one of "
+        f"{[str(r) for r in allowed_roots]}; got {resolved}"
+    )

package/core/cognition/evolve_cli.py

@@ -0,0 +1,55 @@
+"""CLI for the evolve engine: ``python -m core.cognition.evolve_cli``.
+
+Mirrors ``reorganizer_cli``: argparse in, one ``build_proposal`` call,
+human-readable summary out. ``--dry-run`` prints the proposal to stdout
+without writing anything.
+"""
+
+from __future__ import annotations
+
+import argparse
+
+from core.cognition.evolve import build_proposal
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="python -m core.cognition.evolve_cli",
+        description=(
+            "Ingest accumulated signals into instincts and write a "
+            "propose-only evolution proposal."
+        ),
+    )
+    parser.add_argument(
+        "--min-projects", type=int, default=2,
+        help="distinct projects required for a promotion candidate",
+    )
+    parser.add_argument(
+        "--min-confidence", type=float, default=0.8,
+        help="mean confidence required for a promotion candidate",
+    )
+    parser.add_argument(
+        "--dry-run", action="store_true",
+        help="print the proposal to stdout; write nothing",
+    )
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = _build_parser().parse_args(argv)
+    report = build_proposal(
+        dry_run=args.dry_run,
+        min_projects=args.min_projects,
+        min_confidence=args.min_confidence,
+    )
+    if not args.dry_run:
+        print(
+            f"evolve: ingested={report.ingested} "
+            f"pending={report.pending_instincts} "
+            f"candidates={len(report.candidates)} -> {report.proposal_path}"
+        )
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())