arkaos 2.0.2 → 2.0.3

package/VERSION

@@ -1 +1 @@
-2.0.2
+2.0.3

package/config/constitution.yaml

@@ -60,6 +60,8 @@ enforcement_levels:
 
   quality_gate:
     description: "Mandatory pre-delivery review. Nothing ships without APPROVED verdict."
+    trigger: "After the last execution phase, before delivery to user"
+    frequency: "Once per workflow execution, not per phase"
     agents:
       orchestrator:
         id: cqo-marta

package/config/hooks/user-prompt-submit-v2.sh

@@ -7,6 +7,17 @@
 
 input=$(cat)
 
+# ─── V1 Migration Detection ─────────────────────────────────────────────
+V1_PATHS=("$HOME/.claude/skills/arka-os" "$HOME/.claude/skills/arkaos")
+MIGRATION_MARKER="$HOME/.arkaos/migrated-from-v1"
+
+for v1_path in "${V1_PATHS[@]}"; do
+  if [ -d "$v1_path" ] && [ ! -f "$MIGRATION_MARKER" ]; then
+    echo "{\"additionalContext\": \"[MIGRATION] ArkaOS v1 detected at $v1_path. Run: npx arkaos migrate — This will backup v1, preserve your data, and install v2. See: https://github.com/andreagroferreira/arka-os#install\"}"
+    exit 0
+  fi
+done
+
 # ─── Performance Timing ──────────────────────────────────────────────────
 _HOOK_START_NS=$(date +%s%N 2>/dev/null || echo "0")
 _hook_ms() {

package/core/knowledge/__init__.py

@@ -0,0 +1,6 @@
+"""Knowledge system — vector store, chunking, embedding, and retrieval."""
+
+from core.knowledge.chunker import chunk_markdown
+from core.knowledge.vector_store import VectorStore
+
+__all__ = ["VectorStore", "chunk_markdown"]

package/core/knowledge/chunker.py

@@ -0,0 +1,121 @@
+"""Markdown chunker — split documents into embeddable chunks.
+
+Splits on paragraph boundaries, respects heading structure,
+and maintains overlap for context continuity.
+"""
+
+import re
+from dataclasses import dataclass
+
+
+@dataclass
+class Chunk:
+    """A text chunk ready for embedding."""
+    text: str
+    heading: str = ""       # Current heading context
+    index: int = 0          # Position in document
+    source: str = ""        # Source file path
+
+    @property
+    def token_estimate(self) -> int:
+        return len(self.text.split())
+
+
+def chunk_markdown(
+    content: str,
+    max_tokens: int = 512,
+    overlap_tokens: int = 50,
+    source: str = "",
+) -> list[Chunk]:
+    """Split markdown content into chunks at paragraph boundaries.
+
+    Args:
+        content: Markdown text to chunk.
+        max_tokens: Maximum tokens per chunk.
+        overlap_tokens: Token overlap between consecutive chunks.
+        source: Source file path for metadata.
+
+    Returns:
+        List of Chunk objects.
+    """
+    # Strip frontmatter
+    body = content
+    if content.startswith("---"):
+        end = content.find("---", 3)
+        if end != -1:
+            body = content[end + 3:].strip()
+
+    # Split into paragraphs (double newline) preserving headings
+    blocks = re.split(r'\n\n+', body)
+    blocks = [b.strip() for b in blocks if b.strip()]
+
+    chunks: list[Chunk] = []
+    current_heading = ""
+    current_text = ""
+    current_tokens = 0
+
+    for block in blocks:
+        # Track headings
+        heading_match = re.match(r'^(#{1,6})\s+(.+)', block)
+        if heading_match:
+            current_heading = heading_match.group(2)
+
+        block_tokens = len(block.split())
+
+        # If single block exceeds max, split it
+        if block_tokens > max_tokens:
+            if current_text:
+                chunks.append(Chunk(
+                    text=current_text.strip(),
+                    heading=current_heading,
+                    index=len(chunks),
+                    source=source,
+                ))
+                current_text = ""
+                current_tokens = 0
+
+            # Split large block by sentences
+            sentences = re.split(r'(?<=[.!?])\s+', block)
+            for sentence in sentences:
+                sent_tokens = len(sentence.split())
+                if current_tokens + sent_tokens > max_tokens and current_text:
+                    chunks.append(Chunk(
+                        text=current_text.strip(),
+                        heading=current_heading,
+                        index=len(chunks),
+                        source=source,
+                    ))
+                    # Overlap: keep last few words
+                    words = current_text.split()
+                    current_text = " ".join(words[-overlap_tokens:]) + " " if len(words) > overlap_tokens else ""
+                    current_tokens = len(current_text.split())
+                current_text += sentence + " "
+                current_tokens += sent_tokens
+            continue
+
+        # Check if adding this block exceeds limit
+        if current_tokens + block_tokens > max_tokens and current_text:
+            chunks.append(Chunk(
+                text=current_text.strip(),
+                heading=current_heading,
+                index=len(chunks),
+                source=source,
+            ))
+            # Overlap
+            words = current_text.split()
+            current_text = " ".join(words[-overlap_tokens:]) + " " if len(words) > overlap_tokens else ""
+            current_tokens = len(current_text.split())
+
+        current_text += block + "\n\n"
+        current_tokens += block_tokens
+
+    # Final chunk
+    if current_text.strip():
+        chunks.append(Chunk(
+            text=current_text.strip(),
+            heading=current_heading,
+            index=len(chunks),
+            source=source,
+        ))
+
+    return chunks

package/core/knowledge/embedder.py

@@ -0,0 +1,52 @@
+"""Embedding wrapper — local embeddings via fastembed.
+
+Graceful degradation: if fastembed is not installed, returns None
+and the vector store falls back to keyword matching.
+"""
+
+from typing import Optional
+
+# Lazy import — fastembed is optional
+_model = None
+_model_name = "BAAI/bge-small-en-v1.5"  # 384 dims, fast, good quality
+EMBEDDING_DIMS = 384
+
+
+def get_model():
+    """Get or create the embedding model (lazy singleton)."""
+    global _model
+    if _model is None:
+        try:
+            from fastembed import TextEmbedding
+            _model = TextEmbedding(_model_name)
+        except ImportError:
+            return None
+    return _model
+
+
+def embed(text: str) -> Optional[list[float]]:
+    """Embed a single text. Returns None if fastembed unavailable."""
+    model = get_model()
+    if model is None:
+        return None
+    results = list(model.embed([text]))
+    return results[0].tolist() if results else None
+
+
+def embed_batch(texts: list[str]) -> Optional[list[list[float]]]:
+    """Embed multiple texts. Returns None if fastembed unavailable."""
+    if not texts:
+        return []
+    model = get_model()
+    if model is None:
+        return None
+    return [emb.tolist() for emb in model.embed(texts)]
+
+
+def is_available() -> bool:
+    """Check if embedding model is available."""
+    try:
+        from fastembed import TextEmbedding
+        return True
+    except ImportError:
+        return False

package/core/knowledge/indexer.py

@@ -0,0 +1,97 @@
+"""Knowledge indexer — walk directories and index markdown files.
+
+Supports incremental indexing (skips already-indexed files by hash).
+"""
+
+import hashlib
+from pathlib import Path
+from typing import Callable, Optional
+
+from core.knowledge.chunker import chunk_markdown
+from core.knowledge.vector_store import VectorStore
+
+
+def file_hash(path: Path) -> str:
+    """Compute SHA-256 hash of file content."""
+    return hashlib.sha256(path.read_bytes()).hexdigest()[:16]
+
+
+def index_directory(
+    directory: str | Path,
+    store: VectorStore,
+    pattern: str = "**/*.md",
+    on_progress: Optional[Callable[[int, int, str], None]] = None,
+    max_tokens: int = 512,
+    skip_indexed: bool = True,
+) -> dict:
+    """Index all markdown files in a directory.
+
+    Args:
+        directory: Root directory to scan.
+        store: VectorStore to index into.
+        pattern: Glob pattern for files.
+        on_progress: Callback(current, total, filename).
+        max_tokens: Max tokens per chunk.
+        skip_indexed: Skip files already indexed (by hash).
+
+    Returns:
+        Dict with: files_scanned, files_indexed, files_skipped, chunks_created.
+    """
+    root = Path(directory)
+    if not root.exists():
+        return {"files_scanned": 0, "files_indexed": 0, "files_skipped": 0, "chunks_created": 0}
+
+    files = sorted(root.glob(pattern))
+    # Skip hidden dirs (.obsidian, .git)
+    files = [f for f in files if not any(part.startswith(".") for part in f.relative_to(root).parts)]
+
+    total = len(files)
+    indexed = 0
+    skipped = 0
+    chunks_created = 0
+
+    for i, filepath in enumerate(files):
+        if on_progress:
+            on_progress(i + 1, total, filepath.name)
+
+        fhash = file_hash(filepath)
+
+        if skip_indexed and store.is_file_indexed(fhash):
+            skipped += 1
+            continue
+
+        try:
+            content = filepath.read_text(encoding="utf-8")
+        except (OSError, UnicodeDecodeError):
+            skipped += 1
+            continue
+
+        # Skip very small files
+        if len(content.split()) < 20:
+            skipped += 1
+            continue
+
+        # Remove old chunks for this file (re-index)
+        store.remove_file(str(filepath))
+
+        # Chunk and index
+        chunks = chunk_markdown(content, max_tokens=max_tokens, source=str(filepath))
+        if chunks:
+            texts = [c.text for c in chunks]
+            headings = [c.heading for c in chunks]
+            count = store.index_chunks(
+                texts=texts,
+                headings=headings,
+                source=str(filepath),
+                file_hash=fhash,
+                metadata={"relative_path": str(filepath.relative_to(root))},
+            )
+            chunks_created += count
+            indexed += 1
+
+    return {
+        "files_scanned": total,
+        "files_indexed": indexed,
+        "files_skipped": skipped,
+        "chunks_created": chunks_created,
+    }

package/core/knowledge/vector_store.py

@@ -0,0 +1,213 @@
+"""Vector store — SQLite-VSS backed semantic search.
+
+Stores document chunks with embeddings for fast similarity search.
+Graceful degradation: works without sqlite-vss (brute-force fallback).
+"""
+
+import json
+import sqlite3
+import time
+from pathlib import Path
+from typing import Any, Optional
+
+from core.knowledge.embedder import embed, embed_batch, EMBEDDING_DIMS
+
+
+def _load_vss(db: sqlite3.Connection) -> bool:
+    """Try to load sqlite-vss extension."""
+    try:
+        db.enable_load_extension(True)
+        import sqlite_vss
+        sqlite_vss.load(db)
+        return True
+    except (ImportError, Exception):
+        return False
+
+
+class VectorStore:
+    """SQLite-VSS backed vector store for knowledge retrieval."""
+
+    def __init__(self, db_path: str | Path = ":memory:") -> None:
+        self._db_path = str(db_path)
+        self._db = sqlite3.connect(self._db_path)
+        self._db.row_factory = sqlite3.Row
+        self._vss_available = _load_vss(self._db)
+        self._init_schema()
+
+    def _init_schema(self) -> None:
+        """Create tables if they don't exist."""
+        self._db.executescript("""
+            CREATE TABLE IF NOT EXISTS chunks (
+                id INTEGER PRIMARY KEY AUTOINCREMENT,
+                text TEXT NOT NULL,
+                heading TEXT DEFAULT '',
+                source TEXT DEFAULT '',
+                file_hash TEXT DEFAULT '',
+                metadata TEXT DEFAULT '{}',
+                created_at REAL DEFAULT (unixepoch('now')),
+                embedding BLOB
+            );
+            CREATE INDEX IF NOT EXISTS idx_chunks_source ON chunks(source);
+            CREATE INDEX IF NOT EXISTS idx_chunks_hash ON chunks(file_hash);
+        """)
+        if self._vss_available:
+            try:
+                self._db.execute(
+                    f"CREATE VIRTUAL TABLE IF NOT EXISTS vss_chunks USING vss0(embedding({EMBEDDING_DIMS}))"
+                )
+            except Exception:
+                self._vss_available = False
+        self._db.commit()
+
+    def index_chunks(
+        self,
+        texts: list[str],
+        headings: list[str] | None = None,
+        source: str = "",
+        file_hash: str = "",
+        metadata: dict[str, Any] | None = None,
+    ) -> int:
+        """Index multiple text chunks with embeddings.
+
+        Returns number of chunks indexed.
+        """
+        if not texts:
+            return 0
+
+        embeddings = embed_batch(texts)
+        meta_json = json.dumps(metadata or {})
+        count = 0
+
+        for i, text in enumerate(texts):
+            heading = headings[i] if headings and i < len(headings) else ""
+            emb_blob = None
+
+            if embeddings and i < len(embeddings):
+                emb_blob = _vec_to_blob(embeddings[i])
+
+            cursor = self._db.execute(
+                "INSERT INTO chunks (text, heading, source, file_hash, metadata, embedding) VALUES (?, ?, ?, ?, ?, ?)",
+                (text, heading, source, file_hash, meta_json, emb_blob),
+            )
+
+            if self._vss_available and emb_blob:
+                self._db.execute(
+                    "INSERT INTO vss_chunks (rowid, embedding) VALUES (?, ?)",
+                    (cursor.lastrowid, emb_blob),
+                )
+            count += 1
+
+        self._db.commit()
+        return count
+
+    def search(self, query: str, top_k: int = 5) -> list[dict]:
+        """Search for similar chunks.
+
+        Returns list of dicts with: text, heading, source, score, metadata.
+        """
+        # Check if store has any data
+        total = self._db.execute("SELECT COUNT(*) as cnt FROM chunks").fetchone()["cnt"]
+        if total == 0:
+            return []
+
+        query_emb = embed(query)
+
+        if query_emb and self._vss_available:
+            try:
+                return self._vss_search(query_emb, top_k)
+            except Exception:
+                return self._keyword_search(query, top_k)
+
+        # Fallback: keyword search
+        return self._keyword_search(query, top_k)
+
+    def _vss_search(self, query_emb: list[float], top_k: int) -> list[dict]:
+        """Vector similarity search via sqlite-vss."""
+        query_blob = _vec_to_blob(query_emb)
+        rows = self._db.execute("""
+            SELECT c.text, c.heading, c.source, c.metadata, v.distance
+            FROM vss_chunks v
+            JOIN chunks c ON c.id = v.rowid
+            WHERE vss_search(v.embedding, vss_search_params(?, ?))
+        """, (query_blob, top_k)).fetchall()
+
+        return [
+            {
+                "text": r["text"],
+                "heading": r["heading"],
+                "source": r["source"],
+                "score": 1.0 - r["distance"],  # Convert distance to similarity
+                "metadata": json.loads(r["metadata"]),
+            }
+            for r in rows
+        ]
+
+    def _keyword_search(self, query: str, top_k: int) -> list[dict]:
+        """Fallback keyword search when VSS unavailable."""
+        words = query.lower().split()
+        if not words:
+            return []
+
+        conditions = " OR ".join(["lower(text) LIKE ?" for _ in words])
+        params = [f"%{w}%" for w in words[:5]]  # Max 5 keywords
+
+        rows = self._db.execute(
+            f"SELECT text, heading, source, metadata FROM chunks WHERE {conditions} LIMIT ?",
+            params + [top_k],
+        ).fetchall()
+
+        return [
+            {
+                "text": r["text"],
+                "heading": r["heading"],
+                "source": r["source"],
+                "score": 0.5,  # No real score for keyword search
+                "metadata": json.loads(r["metadata"]),
+            }
+            for r in rows
+        ]
+
+    def is_file_indexed(self, file_hash: str) -> bool:
+        """Check if a file has already been indexed."""
+        row = self._db.execute(
+            "SELECT COUNT(*) as cnt FROM chunks WHERE file_hash = ?", (file_hash,)
+        ).fetchone()
+        return row["cnt"] > 0
+
+    def remove_file(self, source: str) -> int:
+        """Remove all chunks from a source file."""
+        if self._vss_available:
+            rows = self._db.execute("SELECT id FROM chunks WHERE source = ?", (source,)).fetchall()
+            for r in rows:
+                self._db.execute("DELETE FROM vss_chunks WHERE rowid = ?", (r["id"],))
+        deleted = self._db.execute("DELETE FROM chunks WHERE source = ?", (source,)).rowcount
+        self._db.commit()
+        return deleted
+
+    def get_stats(self) -> dict:
+        """Get store statistics."""
+        total = self._db.execute("SELECT COUNT(*) as cnt FROM chunks").fetchone()["cnt"]
+        sources = self._db.execute("SELECT COUNT(DISTINCT source) as cnt FROM chunks").fetchone()["cnt"]
+        return {
+            "total_chunks": total,
+            "total_files": sources,
+            "vss_available": self._vss_available,
+            "db_path": self._db_path,
+        }
+
+    def clear(self) -> None:
+        """Remove all data."""
+        if self._vss_available:
+            self._db.execute("DELETE FROM vss_chunks")
+        self._db.execute("DELETE FROM chunks")
+        self._db.commit()
+
+    def close(self) -> None:
+        """Close database connection."""
+        self._db.close()
+
+
+def _vec_to_blob(vec: list[float]) -> bytes:
+    """Convert float vector to bytes for SQLite storage."""
+    import struct
+    return struct.pack(f"{len(vec)}f", *vec)

package/core/runtime/subagent.py

@@ -102,6 +102,11 @@ class SubagentDispatcher:
     The dispatcher creates HandoffArtifacts from agent definitions
     and task descriptions, then delegates to the runtime adapter
     for actual execution.
+
+    Nesting policy: Maximum 1 level of nesting (agent -> subagent).
+    Sub-subagent dispatch is not recommended -- creates context fragmentation
+    and debugging complexity. If a subagent needs help, it should escalate
+    to its squad lead rather than spawning another subagent.
     """
 
     def __init__(self) -> None:

package/core/squads/schema.py

@@ -35,6 +35,9 @@ class SquadMember(BaseModel):
     borrowed: bool = False           # Borrowed from another department?
     source_department: str = ""      # Original department if borrowed
     availability: float = 1.0        # 0.0-1.0, for shared agents
+    # Tier 2 agents can collaborate directly within project squads
+    # without requiring Tier 1 approval for each interaction.
+    can_collaborate_directly: bool = True
 
 
 class SquadWorkflow(BaseModel):

package/core/squads/templates/project-squad.yaml

@@ -0,0 +1,28 @@
+# Project Squad Template
+# Copy and customize for cross-department projects
+id: project-{name}
+name: "{Project Name} Squad"
+description: "Cross-department squad for {project description}"
+department: ""  # No single department — cross-cutting
+squad_type: project
+topology: stream-aligned
+
+members:
+  # Borrow from department squads
+  - agent_id: "{lead-agent-id}"
+    role: "Project Lead"
+    is_lead: true
+    borrowed: true     # Borrowed from department squad
+    availability: 0.5  # 50% allocation
+
+  - agent_id: "{specialist-id}"
+    role: "Technical Implementation"
+    borrowed: true
+    availability: 0.3
+
+# Project squads:
+# - Created by COO (Sofia) or any Squad Lead
+# - Agents are borrowed, not moved
+# - Max 10 members (Two-Pizza Team)
+# - Dissolved when project completes
+# - Quality Gate still mandatory

package/core/synapse/engine.py

@@ -10,6 +10,7 @@ Design goals:
 
 import time
 from dataclasses import dataclass, field
+from typing import Any
 
 from core.synapse.layers import Layer, LayerResult, PromptContext
 from core.synapse.cache import LayerCache
@@ -152,6 +153,7 @@ def create_default_engine(
     constitution_compressed: str = "",
     commands: list[dict] | None = None,
     agents_registry: dict[str, dict] | None = None,
+    vector_store: Any = None,
 ) -> SynapseEngine:
     """Create a SynapseEngine with all 8 default layers.
 
@@ -166,7 +168,7 @@ def create_default_engine(
     from core.synapse.layers import (
         ConstitutionLayer, DepartmentLayer, AgentLayer,
         ProjectLayer, BranchLayer, CommandHintsLayer,
-        QualityGateLayer, TimeLayer,
+        QualityGateLayer, TimeLayer, KnowledgeRetrievalLayer,
     )
 
     engine = SynapseEngine()
@@ -176,6 +178,8 @@ def create_default_engine(
     engine.register_layer(DepartmentLayer())
     engine.register_layer(AgentLayer(agents_registry=agents_registry))
     engine.register_layer(ProjectLayer())
+    if vector_store is not None:
+        engine.register_layer(KnowledgeRetrievalLayer(vector_store=vector_store))
     engine.register_layer(BranchLayer())
     engine.register_layer(CommandHintsLayer(commands=commands))
     engine.register_layer(QualityGateLayer())

package/core/synapse/layers.py

@@ -1,17 +1,18 @@
-"""Synapse layer definitions — the 8 context layers.
+"""Synapse layer definitions — the 9 context layers.
 
 Each layer extracts a specific type of context and compresses it
 for injection into the prompt. Layers are pluggable and ordered.
 
 Layer Architecture:
-  L0: Constitution  — Compressed governance rules (TTL: 300s)
-  L1: Department    — Detected department from input (no cache)
-  L2: Agent         — Agent profile + last gotchas (TTL: 30s)
-  L3: Project       — Active project context (TTL: 30s)
-  L4: Branch        — Current git branch (no cache)
-  L5: Command Hints — Matching commands from registry (TTL: 30s)
-  L6: Quality Gate  — QG status and last verdicts (TTL: 60s)
-  L7: Time          — Time-of-day signal (no cache)
+  L0:   Constitution       — Compressed governance rules (TTL: 300s)
+  L1:   Department         — Detected department from input (no cache)
+  L2:   Agent              — Agent profile + last gotchas (TTL: 30s)
+  L3:   Project            — Active project context (TTL: 30s)
+  L3.5: KnowledgeRetrieval — Semantic search from vector DB (TTL: 30s)
+  L4:   Branch             — Current git branch (no cache)
+  L5:   Command Hints      — Matching commands from registry (TTL: 30s)
+  L6:   Quality Gate       — QG status and last verdicts (TTL: 60s)
+  L7:   Time               — Time-of-day signal (no cache)
 """
 
 import re
@@ -439,3 +440,88 @@ class TimeLayer(Layer):
             layer_id=self.id, tag=tag, content=period,
             tokens_est=1, compute_ms=ms, cached=False,
         )
+
+
+# --- L3.5: Knowledge Retrieval ---
+
+class KnowledgeRetrievalLayer(Layer):
+    """L3.5: Semantic knowledge retrieval from vector DB.
+
+    Searches the local vector store for chunks relevant to the user's
+    input and injects them as context. Gracefully skips if vector store
+    is unavailable or empty.
+    """
+
+    def __init__(self, vector_store: Any = None, max_chunks: int = 3, max_tokens: int = 400) -> None:
+        self._store = vector_store
+        self._max_chunks = max_chunks
+        self._max_tokens = max_tokens
+
+    @property
+    def id(self) -> str:
+        return "L3.5"
+
+    @property
+    def name(self) -> str:
+        return "KnowledgeRetrieval"
+
+    @property
+    def cache_ttl(self) -> int:
+        return 30
+
+    @property
+    def priority(self) -> int:
+        return 35
+
+    def compute(self, ctx: PromptContext) -> LayerResult:
+        start = time.time()
+
+        if not self._store or not ctx.user_input:
+            return LayerResult(
+                layer_id=self.id, tag="", content="",
+                tokens_est=0, compute_ms=0, cached=False,
+            )
+
+        try:
+            results = self._store.search(ctx.user_input, top_k=self._max_chunks)
+        except Exception:
+            return LayerResult(
+                layer_id=self.id, tag="", content="",
+                tokens_est=0, compute_ms=0, cached=False,
+            )
+
+        if not results:
+            ms = int((time.time() - start) * 1000)
+            return LayerResult(
+                layer_id=self.id, tag="", content="",
+                tokens_est=0, compute_ms=ms, cached=False,
+            )
+
+        # Build compact knowledge context
+        snippets = []
+        total_tokens = 0
+        for r in results:
+            text = r["text"][:200].replace("\n", " ").strip()
+            tokens = len(text.split())
+            if total_tokens + tokens > self._max_tokens:
+                break
+            source = r.get("source", "").split("/")[-1] if r.get("source") else ""
+            snippet = f"{source}: {text}" if source else text
+            snippets.append(snippet)
+            total_tokens += tokens
+
+        if not snippets:
+            ms = int((time.time() - start) * 1000)
+            return LayerResult(
+                layer_id=self.id, tag="", content="",
+                tokens_est=0, compute_ms=ms, cached=False,
+            )
+
+        content = " | ".join(snippets)
+        tag = f"[knowledge:{len(snippets)} chunks]"
+        ms = int((time.time() - start) * 1000)
+
+        return LayerResult(
+            layer_id=self.id, tag=tag, content=content,
+            tokens_est=total_tokens, compute_ms=ms, cached=False,
+        )

package/core/tasks/schema.py

@@ -29,6 +29,7 @@ class TaskType(str, Enum):
     RESEARCH = "research"             # Background research
     GENERATION = "generation"         # AI content/image generation
     EXPORT = "export"                 # Export to external system
+    KB_INDEX = "kb_index"           # Index documents into vector store
     CUSTOM = "custom"
 
 

package/departments/dev/agents/research-assistant.yaml

@@ -0,0 +1,51 @@
+id: research-assistant
+name: Maria
+role: Research Assistant
+department: dev
+tier: 3
+
+behavioral_dna:
+  disc:
+    primary: C
+    secondary: S
+    communication_style: "Thorough, detail-oriented, presents findings systematically"
+    under_pressure: "Digs deeper into data before responding"
+    motivator: "Understanding the full picture"
+  enneagram:
+    type: 5
+    wing: 6
+    core_motivation: "To understand and be competent"
+    core_fear: "Being ignorant or uninformed"
+    subtype: social
+  big_five:
+    openness: 90
+    conscientiousness: 85
+    extraversion: 30
+    agreeableness: 70
+    neuroticism: 35
+  mbti:
+    type: INTP
+
+authority:
+  veto: false
+  approve_budget: false
+  approve_architecture: false
+  approve_quality: false
+  block_release: false
+  block_delivery: false
+  orchestrate: false
+  delegates_to: []
+  escalates_to: tech-lead-paulo
+
+expertise:
+  domains: ["research", "documentation", "analysis", "literature-review"]
+  frameworks: ["Systematic Review", "PRISMA", "Research Methodology"]
+  depth: proficient
+  years_equivalent: 5
+
+communication:
+  language: en
+  tone: "Precise and informative"
+  vocabulary_level: specialist
+  preferred_format: "Structured reports with citations"
+  avoid: ["assumptions without evidence", "vague conclusions"]

package/departments/kb/agents/data-collector.yaml

@@ -0,0 +1,51 @@
+id: data-collector
+name: Tomas Jr
+role: Data Collector
+department: kb
+tier: 3
+
+behavioral_dna:
+  disc:
+    primary: C
+    secondary: D
+    communication_style: "Data-driven, factual, structured"
+    under_pressure: "Relies on systematic data collection"
+    motivator: "Complete and accurate data"
+  enneagram:
+    type: 6
+    wing: 5
+    core_motivation: "To have reliable information"
+    core_fear: "Making decisions on incomplete data"
+    subtype: self-preservation
+  big_five:
+    openness: 70
+    conscientiousness: 88
+    extraversion: 35
+    agreeableness: 65
+    neuroticism: 40
+  mbti:
+    type: ISTJ
+
+authority:
+  veto: false
+  approve_budget: false
+  approve_architecture: false
+  approve_quality: false
+  block_release: false
+  block_delivery: false
+  orchestrate: false
+  delegates_to: []
+  escalates_to: kb-lead-clara
+
+expertise:
+  domains: ["data-collection", "web-scraping", "API-integration", "data-validation"]
+  frameworks: ["ETL", "Data Quality Framework"]
+  depth: proficient
+  years_equivalent: 4
+
+communication:
+  language: en
+  tone: "Factual and precise"
+  vocabulary_level: specialist
+  preferred_format: "Data tables with quality scores"
+  avoid: ["subjective interpretations", "unverified claims"]

package/departments/ops/agents/doc-writer.yaml

@@ -0,0 +1,51 @@
+id: doc-writer
+name: Isabel
+role: Documentation Writer
+department: ops
+tier: 3
+
+behavioral_dna:
+  disc:
+    primary: S
+    secondary: C
+    communication_style: "Clear, structured, audience-aware"
+    under_pressure: "Focuses on clarity and completeness"
+    motivator: "Making complex things accessible"
+  enneagram:
+    type: 1
+    wing: 2
+    core_motivation: "To produce correct, helpful documentation"
+    core_fear: "Publishing inaccurate information"
+    subtype: social
+  big_five:
+    openness: 75
+    conscientiousness: 92
+    extraversion: 40
+    agreeableness: 80
+    neuroticism: 30
+  mbti:
+    type: ISFJ
+
+authority:
+  veto: false
+  approve_budget: false
+  approve_architecture: false
+  approve_quality: false
+  block_release: false
+  block_delivery: false
+  orchestrate: false
+  delegates_to: []
+  escalates_to: ops-lead-daniel
+
+expertise:
+  domains: ["technical-writing", "API-docs", "user-guides", "SOPs"]
+  frameworks: ["Diátaxis", "Google Developer Documentation Style"]
+  depth: proficient
+  years_equivalent: 5
+
+communication:
+  language: en
+  tone: "Clear, concise, helpful"
+  vocabulary_level: accessible
+  preferred_format: "Step-by-step guides with examples"
+  avoid: ["jargon without explanation", "walls of text"]

package/departments/pm/agents/pm-director.yaml

@@ -42,7 +42,7 @@ authority:
     - product-owner
     - scrum-master
     - project-coordinator
-  escalates_to: cto-marco
+  escalates_to: coo-sofia
 
 expertise:
   domains:

package/installer/cli.js

@@ -36,6 +36,7 @@ ArkaOS v${VERSION} — The Operating System for AI Agent Teams
 Usage:
   npx arkaos install          Install ArkaOS in current environment
   npx arkaos install --runtime <runtime>  Install for specific runtime
+  npx arkaos init             Initialize project config (.arkaos.json)
   npx arkaos update           Update to latest version
   npx arkaos migrate          Migrate from v1 to v2
   npx arkaos doctor           Run health checks
@@ -57,6 +58,8 @@ Runtimes:
 Examples:
   npx arkaos install                    Auto-detect runtime and install
   npx arkaos install --runtime codex    Install for Codex CLI specifically
+  npx arkaos index                     Index knowledge base (Obsidian vault)
+  npx arkaos search "query"            Search indexed knowledge
   npx arkaos doctor                     Verify installation health
 `);
   process.exit(0);
@@ -69,6 +72,12 @@ async function main() {
       await install({ runtime, path: values.path, force: values.force });
       break;
 
+    case "init": {
+      const { init } = await import("./init.js");
+      await init({ path: values.path || process.cwd() });
+      break;
+    }
+
     case "doctor":
       const { doctor } = await import("./doctor.js");
       await doctor();
@@ -89,6 +98,33 @@ async function main() {
       await migrate();
       break;
 
+    case "index": {
+      const { execSync } = await import("node:child_process");
+      const indexArgs = positionals.slice(1).join(" ");
+      const repoRoot = dirname(fileURLToPath(import.meta.url)).replace(/\/installer$/, "");
+      try {
+        execSync(`python3 "${repoRoot}/scripts/knowledge-index.py" ${indexArgs || "--vault"}`, {
+          stdio: "inherit",
+          env: { ...process.env, ARKAOS_ROOT: repoRoot },
+        });
+      } catch { process.exit(1); }
+      break;
+    }
+
+    case "search": {
+      const { execSync } = await import("node:child_process");
+      const query = positionals.slice(1).join(" ");
+      if (!query) { console.error("Usage: npx arkaos search \"your query\""); process.exit(1); }
+      const repoRoot2 = dirname(fileURLToPath(import.meta.url)).replace(/\/installer$/, "");
+      try {
+        execSync(`python3 "${repoRoot2}/scripts/knowledge-index.py" --search "${query}"`, {
+          stdio: "inherit",
+          env: { ...process.env, ARKAOS_ROOT: repoRoot2 },
+        });
+      } catch { process.exit(1); }
+      break;
+    }
+
     default:
       console.error(`Unknown command: ${command}`);
       console.error('Run "npx arkaos help" for usage information.');

package/installer/init.js

@@ -0,0 +1,105 @@
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { join, basename } from "node:path";
+import { execSync } from "node:child_process";
+
+export async function init({ path }) {
+  const projectDir = path || process.cwd();
+  const configPath = join(projectDir, ".arkaos.json");
+  const projectName = basename(projectDir);
+
+  console.log(`\n  ArkaOS Project Init — ${projectName}\n`);
+
+  // Detect existing config
+  if (existsSync(configPath)) {
+    const existing = JSON.parse(readFileSync(configPath, "utf-8"));
+    console.log(`  Config already exists: ${configPath}`);
+    console.log(`  Department: ${existing.department || "auto"}`);
+    console.log(`  Stack: ${existing.stack || "auto"}`);
+    console.log(`\n  To reconfigure, delete .arkaos.json and run again.\n`);
+    return;
+  }
+
+  // Auto-detect stack
+  const stack = detectStack(projectDir);
+  console.log(`  Detected stack: ${stack}`);
+
+  // Auto-detect department
+  const department = detectDepartment(projectDir, stack);
+  console.log(`  Default department: ${department}`);
+
+  // Create config
+  const config = {
+    name: projectName,
+    department,
+    stack,
+    created: new Date().toISOString(),
+    arkaos_version: "2",
+    settings: {
+      quality_gate: true,
+      obsidian_output: true,
+      auto_index: true,
+    },
+  };
+
+  writeFileSync(configPath, JSON.stringify(config, null, 2) + "\n");
+  console.log(`  Created: ${configPath}`);
+
+  // Create .claude/settings.local.json if Claude Code project
+  const claudeDir = join(projectDir, ".claude");
+  const localSettings = join(claudeDir, "settings.local.json");
+  if (!existsSync(localSettings)) {
+    mkdirSync(claudeDir, { recursive: true });
+    writeFileSync(localSettings, JSON.stringify({
+      permissions: {},
+      hooks: {},
+    }, null, 2) + "\n");
+    console.log(`  Created: .claude/settings.local.json`);
+  }
+
+  console.log(`
+  Project initialized for ArkaOS.
+
+  Config: .arkaos.json
+  Stack:  ${stack}
+  Dept:   ${department}
+
+  ArkaOS will auto-detect this project's context via Synapse L3.
+  Use /dev, /mkt, /brand etc. or just describe what you need.
+  `);
+}
+
+function detectStack(dir) {
+  if (existsSync(join(dir, "composer.json"))) return "laravel";
+  if (existsSync(join(dir, "nuxt.config.ts")) || existsSync(join(dir, "nuxt.config.js"))) return "nuxt";
+  if (existsSync(join(dir, "next.config.js")) || existsSync(join(dir, "next.config.ts")) || existsSync(join(dir, "next.config.mjs"))) return "nextjs";
+  if (existsSync(join(dir, "vite.config.ts"))) {
+    try {
+      const pkg = JSON.parse(readFileSync(join(dir, "package.json"), "utf-8"));
+      if (pkg.dependencies?.vue) return "vue";
+      if (pkg.dependencies?.react) return "react";
+    } catch {}
+    return "vite";
+  }
+  if (existsSync(join(dir, "package.json"))) {
+    try {
+      const pkg = JSON.parse(readFileSync(join(dir, "package.json"), "utf-8"));
+      if (pkg.dependencies?.react) return "react";
+      if (pkg.dependencies?.vue) return "vue";
+      if (pkg.dependencies?.express) return "node-express";
+      return "node";
+    } catch {}
+  }
+  if (existsSync(join(dir, "pyproject.toml")) || existsSync(join(dir, "setup.py"))) return "python";
+  if (existsSync(join(dir, "Gemfile"))) return "ruby";
+  if (existsSync(join(dir, "go.mod"))) return "go";
+  if (existsSync(join(dir, "Cargo.toml"))) return "rust";
+  return "unknown";
+}
+
+function detectDepartment(dir, stack) {
+  // Code projects default to dev
+  if (["laravel", "nuxt", "nextjs", "react", "vue", "node", "python", "ruby", "go", "rust", "node-express", "vite"].includes(stack)) {
+    return "dev";
+  }
+  return "general";
+}

package/installer/migrate.js

@@ -1,4 +1,4 @@
-import { existsSync, readFileSync, renameSync, mkdirSync } from "node:fs";
+import { existsSync, readFileSync, renameSync, mkdirSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { homedir } from "node:os";
 import { execSync } from "node:child_process";
@@ -105,6 +105,9 @@ export async function migrate() {
     process.exit(1);
   }
 
+  // Mark as migrated so hook stops alerting
+  writeFileSync(join(V2_PATH, "migrated-from-v1"), new Date().toISOString());
+
   console.log(`
   Migration complete!
 

package/package.json

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

package/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "arkaos-core"
-version = "2.0.2"
+version = "2.0.3"
 description = "Core engine for ArkaOS — The Operating System for AI Agent Teams"
 readme = "README.md"
 license = {text = "MIT"}
@@ -28,6 +28,10 @@ dependencies = [
 ]
 
 [project.optional-dependencies]
+knowledge = [
+    "fastembed>=0.8.0",
+    "sqlite-vss>=0.1.2",
+]
 dev = [
     "pytest>=8.0",
     "pytest-cov>=5.0",