arkaos 3.77.0 → 4.0.0

package/VERSION

@@ -1 +1 @@
-3.77.0
+4.0.0

package/config/agent-allowlists/laravel.yaml

@@ -1,6 +1,7 @@
 stack: laravel
 baseline:
   - backend-dev
+  - laravel-eng
   - senior-dev
   - architect
   - qa

package/config/agent-allowlists/node.yaml

@@ -1,6 +1,7 @@
 stack: node
 baseline:
   - backend-dev
+  - node-ts-eng
   - senior-dev
   - architect
   - qa

package/config/agent-allowlists/nuxt.yaml

@@ -2,6 +2,7 @@ stack: nuxt
 baseline:
   - frontend-dev
   - backend-dev
+  - node-ts-eng
   - architect
   - qa
   - devops

package/config/agent-allowlists/python.yaml

@@ -1,5 +1,6 @@
 stack: python
 baseline:
+  - python-eng
   - senior-dev
   - architect
   - qa

package/core/agents/registry_gen.py

@@ -27,7 +27,9 @@ def generate_registry(departments_dir: str | Path, output_path: str | Path) -> d
     agents = []
     errors = []
 
-    for yaml_file in sorted(departments_dir.glob("*/agents/*.yaml")):
+    # Recursive: also picks up sub-squad subdirectories
+    # (e.g. dev/agents/backend-core/*.yaml, brand/agents/design-ops/*.yaml).
+    for yaml_file in sorted(departments_dir.glob("*/agents/**/*.yaml")):
         try:
             agent = load_agent(yaml_file)
             entry = {
@@ -36,6 +38,8 @@ def generate_registry(departments_dir: str | Path, output_path: str | Path) -> d
                 "role": agent.role,
                 "department": agent.department,
                 "tier": agent.tier,
+                "parent_squad": agent.parent_squad,
+                "sub_squad_role": agent.sub_squad_role,
                 "disc": {
                     "primary": agent.behavioral_dna.disc.primary.value,
                     "secondary": agent.behavioral_dna.disc.secondary.value,
@@ -60,6 +64,7 @@ def generate_registry(departments_dir: str | Path, output_path: str | Path) -> d
                 },
                 "expertise_domains": agent.expertise.domains[:5],
                 "frameworks": agent.expertise.frameworks[:5],
+                "knowledge_sources": agent.expertise.knowledge_sources,
                 "file": str(yaml_file.relative_to(departments_dir.parent)),
                 "memory_path": agent.memory_path,
             }

package/core/agents/schema.py

@@ -237,6 +237,10 @@ class Expertise(BaseModel):
     """What the agent knows."""
     domains: list[str] = Field(default_factory=list)
     frameworks: list[str] = Field(default_factory=list)
+    knowledge_sources: list[str] = Field(
+        default_factory=list,
+        description="Obsidian KB notes ([[wikilinks]]) that ground this agent's expertise.",
+    )
     depth: str = "expert"  # novice, intermediate, expert, master
     years_equivalent: int = 10
 

package/core/cognition/reorganizer.py

@@ -291,26 +291,56 @@ def _safe_int(value: object) -> int:
         return 0
 
 
-def _redact(text: str) -> str:
+def redact_clients(text: str) -> str:
+    """Redact configured client identifiers from arbitrary text.
+
+    Public, reusable wrapper around the module's compiled redaction regex
+    (loaded from ``~/.arkaos/redaction-clients.json``). Returns the text
+    unchanged when no patterns are configured. Used by any propose-only
+    producer — the reorganizer report and the agent-attribution proposal —
+    so client names never leak into a generated artifact.
+    """
     if _REDACT_RE is None:
         return text
     return _REDACT_RE.sub(_REDACT_TOKEN, text)
 
 
-def _md_escape(text: str) -> str:
-    """Escape markdown control characters that would distort a table row.
+def _redact(text: str) -> str:
+    return redact_clients(text)
+
+
+def md_escape(text: str) -> str:
+    """Neutralise untrusted text for an HTML-rendering markdown viewer.
 
-    Titles and excerpts come from frontmatter the operator controls, but
-    a `|` in a title silently shifts table columns and corrupts the raw-
-    artifact table. Escape pipes, newlines, and stray backticks.
+    Public, reusable wrapper. Titles and excerpts come from untrusted
+    sources (web page titles, YouTube/PDF metadata) and land in .md files
+    that the user opens in viewers such as Obsidian, which render raw HTML
+    inside markdown. To prevent stored HTML/JS injection (CWE-79) we
+    HTML-escape ``<``/``>`` to ``&lt;``/``&gt;`` so any tag renders as
+    literal text. We also escape pipes/backslashes (a ``|`` silently shifts
+    table columns), strip backticks, and flatten newlines so an untrusted
+    title can never distort or execute inside the rendered artifact. Used by
+    the reorganizer report and the agent-attribution proposal.
+
+    Callers redact client names *before* escaping, so the trusted
+    ``<redacted-client>`` marker may already be present; it is preserved
+    verbatim while every other angle bracket is neutralised.
     """
-    return (
+    escaped = (
         text.replace("\\", "\\\\")
+            .replace("<", "&lt;")
+            .replace(">", "&gt;")
             .replace("|", "\\|")
             .replace("\n", " ")
             .replace("\r", " ")
             .replace("`", "")
     )
+    escaped_token = _REDACT_TOKEN.replace("<", "&lt;").replace(">", "&gt;")
+    return escaped.replace(escaped_token, _REDACT_TOKEN)
+
+
+def _md_escape(text: str) -> str:
+    return md_escape(text)
 
 
 def _body_excerpt(body: str) -> str:

package/core/knowledge/agent_match.py

@@ -0,0 +1,114 @@
+"""Semantic agent attribution for a knowledge source (PR3).
+
+Given the knowledge text of a source, suggest WHICH agents should learn
+from it by comparing the source text against each agent's expertise
+profile via local embeddings (``core.knowledge.embedder``).
+
+Pure and propose-only: this module reads agent dicts passed in by the
+caller and NEVER writes agent YAMLs. It degrades gracefully — when the
+embedder is unavailable (fastembed missing) or the source text is empty
+it returns an empty list, and the caller surfaces a reason.
+
+The registry stores ``expertise_domains`` and ``frameworks`` as flat
+list keys on each agent dict (not nested under an ``expertise`` object).
+"""
+
+from __future__ import annotations
+
+import math
+
+from core.knowledge import embedder
+
+_PROFILE_FIELDS = ("expertise_domains", "frameworks")
+_MAX_MATCHED_TERMS = 5
+
+
+def agent_profile_text(agent: dict) -> str:
+    """Build one searchable string from an agent's role + expertise.
+
+    Concatenates role, expertise domains, frameworks, and (optionally)
+    name into a single space-joined string suitable for embedding. Empty
+    fields are skipped so a sparse agent still yields a clean profile.
+    """
+    parts: list[str] = []
+    name = str(agent.get("name") or "").strip()
+    role = str(agent.get("role") or "").strip()
+    if role:
+        parts.append(role)
+    for field in _PROFILE_FIELDS:
+        parts.extend(str(v).strip() for v in agent.get(field) or [] if str(v).strip())
+    if name:
+        parts.append(name)
+    return " ".join(parts)
+
+
+def cosine(a: list[float], b: list[float]) -> float:
+    """Cosine similarity of two vectors; 0.0 if either is empty/zero-norm."""
+    if not a or not b or len(a) != len(b):
+        return 0.0
+    dot = sum(x * y for x, y in zip(a, b))
+    norm_a = math.sqrt(sum(x * x for x in a))
+    norm_b = math.sqrt(sum(y * y for y in b))
+    if norm_a == 0.0 or norm_b == 0.0:
+        return 0.0
+    return dot / (norm_a * norm_b)
+
+
+def _profile_texts(agents: list[dict]) -> list[str]:
+    """Profile text for each agent, preserving order."""
+    return [agent_profile_text(agent) for agent in agents]
+
+
+def _explain_match(source_text: str, agent: dict) -> list[str]:
+    """Up to 5 expertise/framework terms that textually appear in source.
+
+    A cheap, case-insensitive substring "why" explanation — independent of
+    the embedding similarity — so the proposal can show concrete overlap.
+    """
+    haystack = source_text.lower()
+    matched: list[str] = []
+    for field in _PROFILE_FIELDS:
+        for term in agent.get(field) or []:
+            clean = str(term).strip()
+            if clean and clean.lower() in haystack and clean not in matched:
+                matched.append(clean)
+                if len(matched) >= _MAX_MATCHED_TERMS:
+                    return matched
+    return matched
+
+
+def _build_result(source_text: str, agent: dict, score: float) -> dict:
+    """Shape one ranked match for the API response."""
+    return {
+        "id": agent.get("id", ""),
+        "name": agent.get("name", ""),
+        "department": agent.get("department", ""),
+        "role": agent.get("role", ""),
+        "score": round(score, 3),
+        "matched_terms": _explain_match(source_text, agent),
+    }
+
+
+def match_agents(source_text: str, agents: list[dict], top_n: int = 5) -> list[dict]:
+    """Rank agents by semantic similarity of their expertise to the source.
+
+    Returns ``[]`` when ``source_text`` is empty or the embedder is
+    unavailable (caller surfaces a reason). Embeds the source once and the
+    agent profiles in a single batch, then sorts by cosine descending and
+    returns the top ``top_n`` results, each with id/name/department/role/
+    score (0..1, 3dp) and matched_terms. Never writes anything.
+    """
+    if not source_text.strip() or not agents:
+        return []
+    source_vec = embedder.embed(source_text)
+    if source_vec is None:
+        return []
+    agent_vecs = embedder.embed_batch(_profile_texts(agents))
+    if agent_vecs is None:
+        return []
+    scored = [
+        _build_result(source_text, agent, cosine(source_vec, vec))
+        for agent, vec in zip(agents, agent_vecs)
+    ]
+    scored.sort(key=lambda r: r["score"], reverse=True)
+    return scored[: max(top_n, 0)]

package/core/knowledge/chunker.py

@@ -119,3 +119,48 @@ def chunk_markdown(
         ))
 
     return chunks
+
+
+# Minimum contiguous token run treated as a real overlap. The chunker seeds
+# each chunk with the previous chunk's last ``overlap_tokens`` words (default
+# 50), so genuine seams are tens of tokens long. Requiring >= 5 avoids
+# stripping on a 1-2 word coincidence (e.g. both chunks ending/starting "the").
+_MIN_OVERLAP_TOKENS = 5
+
+
+def _overlap_token_count(prev: list[str], cur: list[str], window: int) -> int:
+    """Return length of the longest suffix of ``prev`` that prefixes ``cur``.
+
+    Compares whitespace tokens (never mid-word). Searches the largest possible
+    overlap first within ``window`` and returns the first match, so the result
+    is the true chunker overlap window rather than a short coincidence. Returns
+    0 when no run of at least ``_MIN_OVERLAP_TOKENS`` tokens matches.
+    """
+    max_len = min(len(prev), len(cur), window)
+    for length in range(max_len, _MIN_OVERLAP_TOKENS - 1, -1):
+        if prev[-length:] == cur[:length]:
+            return length
+    return 0
+
+
+def stitch_chunks(texts: list[str], max_overlap_tokens: int = 200) -> str:
+    """Re-join overlapping chunks into a clean transcript, deduping seams.
+
+    ``chunk_markdown`` prepends each chunk with a token-overlap window copied
+    from the previous chunk. Naively joining the chunks therefore repeats that
+    window at every boundary. This detects the actual overlap per adjacent pair
+    (longest suffix-of-prev == prefix-of-cur, on token boundaries, capped at
+    ``max_overlap_tokens``) and strips it from the later chunk before joining
+    with blank lines. No overlap detected -> plain join, so content is never
+    lost. Single chunk returns as-is; empty list returns "".
+    """
+    parts = [t for t in texts if t]
+    if not parts:
+        return ""
+    result = [parts[0]]
+    for cur in parts[1:]:
+        prev_tokens = result[-1].split()
+        cur_tokens = cur.split()
+        overlap = _overlap_token_count(prev_tokens, cur_tokens, max_overlap_tokens)
+        result.append(" ".join(cur_tokens[overlap:]) if overlap else cur)
+    return "\n\n".join(p for p in result if p)