arkaos 4.37.0 → 4.38.0

package/README.md

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

package/THE-ARKAOS-GUIDE.md

@@ -1,6 +1,6 @@
 # The ArkaOS Guide
 
-> v4.36.0 — 89 agents, 17 departments, 331 skills, 297 commands, 17 ADRs.
+> v4.38.0 — 89 agents, 17 departments, 332 skills, 297 commands, 17 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.37.0
+4.38.0

package/arka/SKILL.md

@@ -47,7 +47,7 @@ complementary, not alternatives.
 # ArkaOS — Main Orchestrator
 
 > **The Operating System for AI Agent Teams**
-> 89 agents. 17 departments. 331 skills. Multi-runtime. Dashboard. Knowledge RAG.
+> 89 agents. 17 departments. 332 skills. Multi-runtime. Dashboard. Knowledge RAG.
 
 ## ⛔ Evidence flow — 4 gates (NON-NEGOTIABLE)
 

package/config/skills-curated.yaml

@@ -24,8 +24,8 @@ curated_subskills:
   community: [moderation]
   content: [calendar, hook-write]
   dev: [api-design, architecture-design, clean-code-review, code-review,
-        db-design, diagram, refactor-plan, runbook, security-audit, spec,
-        tdd-cycle, watch]
+        db-design, diagram, refactor-plan, runbook, scroll-world,
+        security-audit, spec, tdd-cycle, watch]
   ecom: [cart-recovery, store-audit]
   finance: [financial-model, unit-economics]
   kb: [search-kb, zettelkasten-process]

package/config/skills-provenance.yaml

@@ -91,6 +91,13 @@ derived:
     origin: community
     source: https://github.com/nutlope/hallmark
     license: MIT
+  # Scroll-world — scroll-scrubbed "fly through the world" landing pages
+  # (Higgsfield pipeline + portable scrub engine), vendored verbatim with
+  # ArkaOS frontmatter; THIRD-PARTY-NOTICES records the trail.
+  departments/dev/skills/scroll-world:
+    origin: community
+    source: https://github.com/oso95/scroll-world
+    license: MIT
   # Watch absorption campaign — video-input primitive derived from
   # bradautomates/claude-video v0.2.0 (MIT), maintained natively.
   departments/dev/skills/watch:

package/core/hooks/session_start.py

@@ -341,16 +341,30 @@ def build_recap(cwd: str, budget_ms: int = _BUDGET_MS) -> str:
         if not records or (time.monotonic() - start) * 1000 > budget_ms:
             return ""
         lines = ["[SESSION-MEMORY] Prior turns (importance+recency — not semantic):"]
+        handoff = store.cross_runtime_handoff(project, "claude")
+        if handoff:
+            stamp = (
+                handoff.ts[11:16] + "Z" if len(handoff.ts) >= 16 else handoff.ts
+            )
+            h_summary = neutralize_summary(handoff.summary)[:_SUMMARY_CHARS]
+            tail = f": {h_summary}" if h_summary else ""
+            lines.append(
+                f"[arka:handoff] última sessão em {handoff.runtime}"
+                f" ({stamp}){tail}"
+            )
+        turn_lines = 0
         for record in records:
             summary = neutralize_summary(record.summary)[:_SUMMARY_CHARS]
             if not summary:
                 continue
-            lines.append(f"[SESSION-MEMORY] - {record.ts[:10]}: {summary}")
-        if len(lines) == 1:
+            runtime = f" · {record.runtime}" if record.runtime else ""
+            lines.append(f"[SESSION-MEMORY] - {record.ts[:10]}{runtime}: {summary}")
+            turn_lines += 1
+        if turn_lines == 0:
             return ""
         backends = ",".join(sorted({r.embedding_backend for r in records})) or "none"
         lines.append(
-            f"[SESSION-MEMORY] shown: {len(lines) - 1} turns ({project}),"
+            f"[SESSION-MEMORY] shown: {turn_lines} turns ({project}),"
             f" backends={backends}"
         )
         return "\n".join(lines)

package/core/memory/semantic_store.py

@@ -46,6 +46,7 @@ class TurnRecord(BaseModel):
     id: str = Field(default_factory=lambda: uuid.uuid4().hex)
     ts: str = ""
     session_id: str = ""
+    runtime: str = ""
     project_name: str = ""
     cwd: str = ""
     summary: str = ""
@@ -110,6 +111,7 @@ class SessionMemoryStore:
                     id TEXT PRIMARY KEY,
                     ts TEXT NOT NULL,
                     session_id TEXT NOT NULL,
+                    runtime TEXT NOT NULL DEFAULT '',
                     project_name TEXT NOT NULL DEFAULT '',
                     cwd TEXT NOT NULL DEFAULT '',
                     summary TEXT NOT NULL DEFAULT '',
@@ -122,13 +124,23 @@ class SessionMemoryStore:
                     dims INTEGER NOT NULL DEFAULT 0
                 )
             """)
+            self._migrate(conn)
+
+    def _migrate(self, conn: sqlite3.Connection) -> None:
+        """Additive column migrations for DBs created before a column
+        existed — CREATE TABLE IF NOT EXISTS never alters a live table."""
+        cols = {row[1] for row in conn.execute("PRAGMA table_info(turns)")}
+        if "runtime" not in cols:
             conn.execute(
-                "CREATE INDEX IF NOT EXISTS idx_turns_project_ts "
-                "ON turns (project_name, ts DESC)"
-            )
-            conn.execute(
-                "CREATE INDEX IF NOT EXISTS idx_turns_session ON turns (session_id)"
+                "ALTER TABLE turns ADD COLUMN runtime TEXT NOT NULL DEFAULT ''"
             )
+        conn.execute(
+            "CREATE INDEX IF NOT EXISTS idx_turns_project_ts "
+            "ON turns (project_name, ts DESC)"
+        )
+        conn.execute(
+            "CREATE INDEX IF NOT EXISTS idx_turns_session ON turns (session_id)"
+        )
 
     def save(self, record: TurnRecord) -> None:
         row = record.model_dump()
@@ -139,12 +151,13 @@ class SessionMemoryStore:
         )
         with closing(self._conn()) as conn, conn:
             conn.execute(
-                "INSERT OR REPLACE INTO turns (id, ts, session_id, project_name,"
-                " cwd, summary, tools_used, file_paths, importance, embedding,"
-                " embedding_backend, embedding_model, dims)"
-                " VALUES (:id, :ts, :session_id, :project_name, :cwd, :summary,"
-                " :tools_used, :file_paths, :importance, :embedding,"
-                " :embedding_backend, :embedding_model, :dims)",
+                "INSERT OR REPLACE INTO turns (id, ts, session_id, runtime,"
+                " project_name, cwd, summary, tools_used, file_paths,"
+                " importance, embedding, embedding_backend, embedding_model,"
+                " dims)"
+                " VALUES (:id, :ts, :session_id, :runtime, :project_name,"
+                " :cwd, :summary, :tools_used, :file_paths, :importance,"
+                " :embedding, :embedding_backend, :embedding_model, :dims)",
                 row,
             )
 
@@ -185,6 +198,40 @@ class SessionMemoryStore:
         where = f"WHERE {' AND '.join(clauses)}" if clauses else ""
         return where, params
 
+    def latest_turn(
+        self, project_name: str, exclude_session: str | None = None
+    ) -> TurnRecord | None:
+        """Newest turn in the project — the handoff-detection primitive."""
+        where, params = self._scope(project_name, exclude_session)
+        with closing(self._conn()) as conn:
+            row = conn.execute(
+                f"SELECT * FROM turns {where} ORDER BY ts DESC LIMIT 1",
+                params,
+            ).fetchone()
+        return self._row_to_record(row) if row else None
+
+    def cross_runtime_handoff(
+        self,
+        project_name: str,
+        current_runtime: str,
+        exclude_session: str | None = None,
+        max_age_h: float = 24,
+    ) -> TurnRecord | None:
+        """Newest turn in the project captured by a DIFFERENT runtime,
+        fresh enough to matter as a continuation hint — the shared
+        handoff predicate for every runtime's entry point."""
+        latest = self.latest_turn(project_name, exclude_session=exclude_session)
+        if not latest or not latest.runtime or latest.runtime == current_runtime:
+            return None
+        try:
+            age_h = (
+                datetime.now(UTC)
+                - datetime.fromisoformat(latest.ts.replace("Z", "+00:00"))
+            ).total_seconds() / 3600
+        except ValueError:
+            return None
+        return latest if age_h <= max_age_h else None
+
     def keyword_search(
         self, query: str, project_name: str | None = None, top_k: int = 3
     ) -> list[dict]:

package/core/memory/turn_capture.py

@@ -161,7 +161,8 @@ def _precompute_cache(
         "dims": record.dims,
         "items": [
             {"summary": i["summary"][:200], "project_name": i["project_name"],
-             "ts": i["ts"], "score": i["score"], "retrieval": i["retrieval"]}
+             "ts": i["ts"], "score": i["score"], "retrieval": i["retrieval"],
+             "runtime": i.get("runtime", "")}
             for i in items
         ],
     }
@@ -190,14 +191,16 @@ def _maintenance(store: SessionMemoryStore) -> None:
     store.prune()
 
 
-def capture_turn(session_id: str, transcript_path: str, cwd: str = "") -> int:
-    if not _config_enabled() or not session_id:
-        return 0
-    raw = _read_tail(transcript_path)
-    if not raw:
-        return 0
-    text = _last_assistant_text(transcript_path, raw)
-    tools, paths = _parse_tool_uses(raw)
+def _persist_record(
+    session_id: str,
+    text: str,
+    cwd: str,
+    runtime: str,
+    tools: list[str],
+    paths: list[str],
+) -> None:
+    """Shared tail for every capture path: sanitize -> embed -> store ->
+    precompute the F1-A3 neighbour cache -> amortised maintenance."""
     summary, sanitized_ok = _sanitized_summary(text)
     tools = _safe_tool_names(tools, sanitized_ok)
     if not sanitized_ok:
@@ -206,6 +209,7 @@ def capture_turn(session_id: str, transcript_path: str, cwd: str = "") -> int:
     record = TurnRecord(
         ts=datetime.now(UTC).isoformat(),
         session_id=session_id,
+        runtime=runtime,
         project_name=Path(cwd).name if cwd else "",
         cwd=cwd,
         summary=summary,
@@ -221,6 +225,31 @@ def capture_turn(session_id: str, transcript_path: str, cwd: str = "") -> int:
     store.save(record)
     _precompute_cache(store, record, session_id)
     _maintenance(store)
+
+
+def capture_turn(
+    session_id: str, transcript_path: str, cwd: str = "", runtime: str = "claude"
+) -> int:
+    if not _config_enabled() or not session_id:
+        return 0
+    raw = _read_tail(transcript_path)
+    if not raw:
+        return 0
+    text = _last_assistant_text(transcript_path, raw)
+    tools, paths = _parse_tool_uses(raw)
+    _persist_record(session_id, text, cwd, runtime, tools, paths)
+    return 0
+
+
+def capture_text_turn(
+    session_id: str, text: str, cwd: str = "", runtime: str = "opencode"
+) -> int:
+    """Transcript-free capture for runtimes without a Claude-style JSONL
+    transcript on disk (OpenCode: the plugin holds the messages, not us).
+    The caller hands over the last assistant text directly."""
+    if not _config_enabled() or not session_id or not text.strip():
+        return 0
+    _persist_record(session_id, text, cwd, runtime, [], [])
     return 0
 
 
@@ -261,14 +290,30 @@ def main(argv: list[str] | None = None) -> int:
             return run_maintenance()
         except Exception:  # detached worker must die quietly
             return 0
+    if args and args[0] == "capture-text":
+        if len(args) < 4:
+            print(
+                "usage: python3 -m core.memory.turn_capture"
+                " capture-text <session_id> <cwd> <runtime>  (text on stdin)"
+            )
+            return 2
+        try:
+            text = sys.stdin.read()
+            return capture_text_turn(args[1], text, args[2], args[3])
+        except Exception:  # detached worker must die quietly
+            return 0
     if len(args) < 2:
         print(
             "usage: python3 -m core.memory.turn_capture"
-            " (<session_id> <transcript_path> [cwd] | maintenance)"
+            " (<session_id> <transcript_path> [cwd] [runtime] |"
+            " capture-text <session_id> <cwd> <runtime> | maintenance)"
         )
         return 2
     try:
-        return capture_turn(args[0], args[1], args[2] if len(args) > 2 else "")
+        return capture_turn(
+            args[0], args[1], args[2] if len(args) > 2 else "",
+            args[3] if len(args) > 3 else "claude",
+        )
     except Exception:  # detached worker must die quietly
         return 0
 

package/core/runtime/opencode_hooks.py

@@ -9,6 +9,10 @@ gets the same governance stack as the Claude runtime:
     pre_tool  research gate + frontend gate (PreToolUse parity)
     post_tool MCP usage telemetry (PostToolUse parity)
     idle      kb-citation + [arka:meta] compliance (Stop-hook parity)
+              + detached turn capture into the shared cross-runtime
+              session memory (core.memory.turn_capture capture-text)
+    memory    L9.5 parity — cross-runtime session memory retrieval +
+              once-per-session handoff digest on the prompt hot path
     compact   gate state context (PreCompact parity)
 
 CLI contract::
@@ -23,7 +27,9 @@ same posture as the bash hooks it mirrors).
 from __future__ import annotations
 
 import json
+import os
 import re
+import subprocess
 import sys
 from datetime import datetime, timezone
 from pathlib import Path
@@ -115,11 +121,69 @@ def _store_prompt(session_id: str, prompt: str) -> None:
         pass
 
 
+def _load_commands_registry() -> list[dict]:
+    """knowledge/commands-registry.json from the repo root arka-py runs
+    against (PYTHONPATH chain: .repo-path -> dev checkout -> lib)."""
+    path = Path(__file__).resolve().parents[2] / "knowledge" / "commands-registry.json"
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+        commands = data.get("commands", [])
+        return commands if isinstance(commands, list) else []
+    except (OSError, json.JSONDecodeError):
+        return []
+
+
+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: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."""
+    from core.hooks.user_prompt_submit import (
+        _ROUTE_REMINDER,
+        _WF_VERB_RE,
+        _WORKFLOW_DIRECTIVE,
+    )
+
+    lines = [_ROUTE_REMINDER.strip()]
+    if not prompt:
+        return lines
+    try:
+        from core.synapse.layers import (
+            CommandHintsLayer,
+            DepartmentLayer,
+            PromptContext,
+        )
+
+        ctx = PromptContext(
+            user_input=prompt,
+            cwd=cwd,
+            project_name=Path(cwd).name if cwd else "",
+            runtime_id="opencode",
+            extra={"session_id": session_id},
+        )
+        dept = DepartmentLayer().compute(ctx)
+        if dept.tag:
+            lines.append(dept.tag)
+        commands = _load_commands_registry()
+        if commands:
+            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
+        pass
+    if prompt[0] not in ("/", "!") and _WF_VERB_RE.search(prompt):
+        lines.append(_WORKFLOW_DIRECTIVE.strip())
+    return lines
+
+
 def _action_prompt(payload: dict) -> dict:
-    """Token-hygiene parity (config/hooks/token-hygiene.sh)."""
+    """Token-hygiene parity (config/hooks/token-hygiene.sh) + the routing
+    injection (UserPromptSubmit parity) that makes /arka optional."""
     prompt = str(payload.get("prompt", ""))
     session_id = str(payload.get("session_id", ""))
     suggestions: list[str] = []
+    routing = _routing_lines(prompt, session_id, str(payload.get("cwd", "")))
 
     ctx = payload.get("context_pct")
     if isinstance(ctx, (int, float)):
@@ -157,7 +221,7 @@ def _action_prompt(payload: dict) -> dict:
             "ficheiro concreto."
         )
 
-    return {"suggestions": suggestions}
+    return {"suggestions": suggestions, "routing": routing}
 
 
 def _action_pre_tool(payload: dict) -> dict:
@@ -230,8 +294,38 @@ def _action_post_tool(payload: dict) -> dict:
     return {"recorded_mcp": recorded}
 
 
+def _enqueue_turn_capture(session_id: str, text: str, cwd: str) -> None:
+    """F1-A2 parity: fire-and-forget semantic turn capture — the same
+    detached-worker pattern as core/hooks/stop.py, fed with the assistant
+    text directly (OpenCode has no Claude-style JSONL transcript)."""
+    if not session_id or not text.strip():
+        return
+    repo = Path(__file__).resolve().parents[2]
+    if not (repo / "core" / "memory" / "turn_capture.py").is_file():
+        return
+    try:
+        proc = subprocess.Popen(
+            [sys.executable, "-m", "core.memory.turn_capture",
+             "capture-text", session_id, cwd or "", "opencode"],
+            stdin=subprocess.PIPE,
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+            env={**os.environ, "PYTHONPATH": str(repo)},
+            start_new_session=True,
+        )
+        if proc.stdin:
+            try:
+                proc.stdin.write(text.encode("utf-8", "replace"))
+                proc.stdin.close()
+            except (BrokenPipeError, OSError):
+                pass
+    except Exception:  # noqa: BLE001 — a hook bridge never breaks a turn
+        pass
+
+
 def _action_idle(payload: dict) -> dict:
-    """Stop-hook parity: kb-citation + [arka:meta] compliance (soft)."""
+    """Stop-hook parity: kb-citation + [arka:meta] compliance (soft),
+    plus detached turn capture into the shared cross-runtime memory."""
     text = str(payload.get("response_text", ""))
     session_id = str(payload.get("session_id", ""))
     nudges: list[str] = []
@@ -248,6 +342,8 @@ def _action_idle(payload: dict) -> dict:
             "fecha com kb=N research=X persona=Y gap=Z critic=W."
         )
 
+    _enqueue_turn_capture(session_id, text, str(payload.get("cwd", "")))
+
     _append_jsonl(
         _TELEMETRY_DIR / "opencode-compliance.jsonl",
         {
@@ -261,6 +357,94 @@ def _action_idle(payload: dict) -> dict:
     return {"nudges": nudges}
 
 
+_HANDOFF_MAX_AGE_H = 24
+_HANDOFF_SUMMARY_CHARS = 160
+
+
+def _handoff_marker(session_id: str) -> Path:
+    safe = re.sub(r"[^A-Za-z0-9_-]", "", session_id or "default")
+    return _PROMPT_CACHE_DIR / f"opencode-handoff-{safe}.json"
+
+
+def _handoff_line(session_id: str, project: str) -> str:
+    """Once per session: when the newest turn in this project was captured
+    by ANOTHER runtime, surface it — that is the cross-runtime handoff."""
+    if not project or _handoff_marker(session_id).exists():
+        return ""
+    from core.memory.semantic_store import (
+        SessionMemoryStore,
+        default_db_path,
+        neutralize_summary,
+    )
+
+    if not default_db_path().is_file():
+        return ""
+    latest = SessionMemoryStore().cross_runtime_handoff(
+        project, "opencode", exclude_session=session_id,
+        max_age_h=_HANDOFF_MAX_AGE_H,
+    )
+    if not latest:
+        return ""
+    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()}),
+            encoding="utf-8",
+        )
+    except OSError:
+        pass
+    summary = neutralize_summary(latest.summary)[:_HANDOFF_SUMMARY_CHARS]
+    stamp = latest.ts[11:16] + "Z" if len(latest.ts) >= 16 else latest.ts
+    tail = f": {summary}" if summary else ""
+    return f"[arka:handoff] última sessão em {latest.runtime} ({stamp}){tail}"
+
+
+def _action_memory(payload: dict) -> dict:
+    """L9.5 parity for the prompt hot path: pre-ranked semantic neighbours
+    + live scoped keyword hits from the shared cross-runtime store, plus
+    the once-per-session handoff digest. Never embeds — zero cost here."""
+    prompt = str(payload.get("prompt", ""))
+    session_id = str(payload.get("session_id", ""))
+    cwd = str(payload.get("cwd", ""))
+    lines: list[str] = []
+    try:
+        from core.synapse.session_memory_layer import (
+            _format_item,
+            _l95_feature_flag_on,
+            _read_session_cache,
+        )
+
+        if not _l95_feature_flag_on():
+            return {"context": []}
+        seen: set[str] = set()
+        items, ranked_at = _read_session_cache(session_id)
+        for item in items:
+            line = _format_item(item, ranked_at)
+            if line and item.get("summary") not in seen:
+                seen.add(item.get("summary"))
+                lines.append(line)
+        project = Path(cwd).name if cwd else ""
+        if prompt and project:
+            from core.memory.semantic_store import (
+                SessionMemoryStore,
+                default_db_path,
+            )
+
+            if default_db_path().is_file():
+                hits = SessionMemoryStore().keyword_search(prompt, project, top_k=2)
+                for hit in hits:
+                    line = _format_item(hit)
+                    if line and hit.get("summary") not in seen:
+                        seen.add(hit.get("summary"))
+                        lines.append(line)
+        handoff = _handoff_line(session_id, project)
+        if handoff:
+            lines.insert(0, handoff)
+    except Exception:  # noqa: BLE001 — memory is a bonus, never a blocker
+        return {"context": []}
+    return {"context": lines[:6]}
+
+
 def _action_compact(payload: dict) -> dict:
     """PreCompact parity: carry gate state across compaction."""
     from core.workflow import state
@@ -286,6 +470,7 @@ _ACTIONS = {
     "pre_tool": _action_pre_tool,
     "post_tool": _action_post_tool,
     "idle": _action_idle,
+    "memory": _action_memory,
     "compact": _action_compact,
 }
 

package/departments/dev/skills/animated-website/SKILL.md

@@ -8,8 +8,10 @@ description: >
   TRIGGER: "animated website", "scroll animation", "video to website",
   "Apple-style page", "site com scroll do vídeo", "transforma este vídeo num
   site", "frame animation", "/dev animated-website". SKIP: embedding a plain
-  video player -> just use <video>; regular animated site WITHOUT a video
-  source -> frontend-design skill; video editing/production -> content/video-produce.
+  video player -> just use <video>; generating a scroll-scrubbed 3D world
+  FROM SCRATCH via Higgsfield (no existing video source) -> dev/scroll-world;
+  regular animated site WITHOUT a video source -> frontend-design skill;
+  video editing/production -> content/video-produce.
 allowed-tools: [Read, Write, Edit, Bash, Grep, Glob, Agent, WebFetch]
 metadata:
   origin: community