arkaos 4.22.0 → 4.24.0

package/README.md

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

package/THE-ARKAOS-GUIDE.md

@@ -0,0 +1,72 @@
+# The ArkaOS Guide
+
+> v4.24.0 — 86 agents, 17 departments, 294 skills, 270 commands, 16 ADRs.
+> One file, everything you need to start. Generated by `scripts/guide_gen.py` — never hand-edited.
+
+## What it is
+
+ArkaOS is an operating system for AI agent teams: specialized
+departments with framework-backed agents, a constitution with a
+Quality Gate that holds veto power, and an evidence flow where
+gates pass on tool output read from disk — never on narration.
+
+## Start here
+
+```bash
+npx arkaos install     # detects your runtime, installs the core
+npx arkaos doctor      # canonical health check (venv, hooks,
+                       # fastpath, security advisory)
+```
+
+Then inside your runtime: `/arka setup` (profile) and `/do <what
+you need>` — plain language routes to the right department.
+
+## Keep it updated (two steps)
+
+```bash
+npx arkaos@latest update   # step 1: core, hooks, CLI
+```
+
+Then `/arka update` inside the runtime — step 2 syncs every
+project (skills, MCP configs, settings, stack rules).
+
+## Departments
+
+Every request routes through a department squad — ArkaOS never
+answers as a generic assistant.
+
+| Prefix | Commands |
+|---|---|
+| `/arka` | 22 |
+| `/brand` | 12 |
+| `/community` | 14 |
+| `/content` | 19 |
+| `/dev` | 36 |
+| `/do` | 1 |
+| `/ecom` | 18 |
+| `/fin` | 10 |
+| `/kb` | 22 |
+| `/landing` | 14 |
+| `/lead` | 10 |
+| `/mkt` | 12 |
+| `/ops` | 24 |
+| `/org` | 10 |
+| `/pm` | 12 |
+| `/saas` | 14 |
+| `/sales` | 10 |
+| `/strat` | 10 |
+
+## How work ships
+
+1. **G1 CONTEXT** — routing + grounding before anything runs.
+2. **G2 PLAN** — explicit approval before code.
+3. **G3 EXECUTE** — real test runs with exit codes on record.
+4. **G4 REVIEW** — the Quality Gate (CQO + copy + tech reviewers)
+   issues a binary APPROVED/REJECTED; failing evidence can never
+   be overridden by narrative.
+
+## Go deeper
+
+- Wiki: https://github.com/andreagroferreira/arka-os/wiki
+- npm: https://www.npmjs.com/package/arkaos
+- Dashboard: `npx arkaos dashboard` (localhost:3333)

package/VERSION

@@ -1 +1 @@
-4.22.0
+4.24.0

package/arka/SKILL.md

@@ -7,25 +7,47 @@ description: >
 allowed-tools: [Read, Write, Edit, Bash, Grep, Glob, Agent, WebFetch, WebSearch]
 ---
 
-## KB-First Research (non-negotiable)
+## KB-First Research (`always-research` SHOULD)
 
 Canonical home of the doctrine — every skill's compact
-`arka:kb-first-prefix` pointer references this section. Before any
+`arka:kb-first-prefix` pointer references this section. The Knowledge Base
+has two co-equal faces over the same corpus: **Obsidian** (note content)
+and **Graphify** (the knowledge graph — how concepts connect). Before any
 external research (Context7, WebSearch, WebFetch, Firecrawl):
 
 1. Call `mcp__obsidian__search_notes` on the query first.
-2. Cite relevant hits with `[[wikilinks]]` or explicitly declare a KB gap.
-3. Only after (1) and (2) may external tools run.
+2. When Graphify is configured, also call `mcp__graphify__query_graph`
+   (or `god_nodes` / `shortest_path`) for the relationship view.
+3. Cite relevant hits with `[[wikilinks]]` and/or graph nodes, or
+   explicitly declare a KB gap.
+4. Only after (1)–(3) may external tools run.
+
+**Fail-open:** Graphify runs on a per-user endpoint (home LAN, localhost,
+or VPS — see `knowledge.graphify` config). When it is not configured or
+not reachable, treat it as a gap and proceed with Obsidian alone; never
+block a turn waiting on it. Obsidian remains the mandatory first step.
 
 The Synapse L2.5 layer pre-injects top KB matches on every user prompt;
 treat them as your default source. External research supplements the vault;
-it does not replace it. Enforcement: the Stop hook's kb-cite check
-measures citation compliance per turn.
+it does not replace it.
+
+**Enforcement** runs on three surfaces, in the order they fire:
+
+| Surface | Effect |
+| --- | --- |
+| PreToolUse gate (`core/workflow/research_gate.py`) | DENIES the tool call in the current turn on a repeat violation |
+| Quality Gate | DOD item `kb-research-cited` (`definition_of_done.universal`) is `hard: true` — a failed hard item blocks the done marker (rule `definition-of-done-per-domain`) |
+| Stop hook (`core/governance/kb_cite_check.py`) | SOFT — measures citation compliance and nudges the next turn, never blocks this one |
+
+Governing rule: `always-research` (SHOULD, `config/constitution.yaml`).
+`kb-research-cited` is a Definition-of-Done item (`hard: true`), not an
+entry in the must/should/non-negotiable rule lists — the two are
+complementary, not alternatives.
 
 # ArkaOS — Main Orchestrator
 
 > **The Operating System for AI Agent Teams**
-> 86 agents. 17 departments. 292 skills. Multi-runtime. Dashboard. Knowledge RAG.
+> 86 agents. 17 departments. 294 skills. Multi-runtime. Dashboard. Knowledge RAG.
 
 ## ⛔ Evidence flow — 4 gates (NON-NEGOTIABLE)
 

package/arka/skills/bootstrap-agent/SKILL.md

@@ -16,8 +16,9 @@ allowed-tools: [Agent, Read, Write, Bash]
 ---
 
 <!-- arka:kb-first-prefix begin -->
-> **KB-first:** query `mcp__obsidian__search_notes` and cite
-> `[[wikilinks]]` — or declare the gap — BEFORE any external research.
+> **KB-first:** query `mcp__obsidian__search_notes` (and
+> `mcp__graphify__query_graph` when configured) and cite `[[wikilinks]]`
+> or graph nodes — or declare the gap — BEFORE any external research.
 > Full doctrine: `arka/SKILL.md` (KB-First Research).
 <!-- arka:kb-first-prefix end -->
 

package/arka/skills/conclave/SKILL.md

@@ -72,6 +72,17 @@ Your style: {communication_style}. Your framework: {decision_framework}.
 Respond in 3-5 sentences as {name} would. Be specific. Channel their actual thinking.
 ```
 
+## Independence discipline (anti-anchoring)
+
+Generate each advisor's take in an isolated context: the advisor sees the
+question and their own persona, never another advisor's answer. Anchoring
+is the failure mode this prevents — the first plausible take pulls every
+later one toward it, and ten dependent opinions collapse into one opinion
+with ten signatures. Disagreement between advisors is the signal the
+synthesis step exists to surface; only the synthesis (and the debate's
+disagreement pass) may read all ten. In `debate`, opening positions are
+likewise collected independently BEFORE the rebuttal round.
+
 ## Advisor Deep Dive: `/arka conclave advisor <name>`
 
 Full advisor profile: all 4 DNA frameworks, mental models with key questions, communication style, decision framework, sources, why matched (aligned/contrarian, score, dimension comparison).

package/arka/skills/flow/SKILL.md

@@ -18,8 +18,9 @@ allowed-tools: [Read, Write, Edit, Bash, Grep, Glob, Agent, WebFetch, WebSearch]
 ---
 
 <!-- arka:kb-first-prefix begin -->
-> **KB-first:** query `mcp__obsidian__search_notes` and cite
-> `[[wikilinks]]` — or declare the gap — BEFORE any external research.
+> **KB-first:** query `mcp__obsidian__search_notes` (and
+> `mcp__graphify__query_graph` when configured) and cite `[[wikilinks]]`
+> or graph nodes — or declare the gap — BEFORE any external research.
 > Full doctrine: `arka/SKILL.md` (KB-First Research).
 <!-- arka:kb-first-prefix end -->
 

package/arka/skills/forge/SKILL.md

@@ -19,8 +19,9 @@ allowed-tools: [Read, Write, Edit, Bash, Grep, Glob, Agent, WebFetch, WebSearch]
 ---
 
 <!-- arka:kb-first-prefix begin -->
-> **KB-first:** query `mcp__obsidian__search_notes` and cite
-> `[[wikilinks]]` — or declare the gap — BEFORE any external research.
+> **KB-first:** query `mcp__obsidian__search_notes` (and
+> `mcp__graphify__query_graph` when configured) and cite `[[wikilinks]]`
+> or graph nodes — or declare the gap — BEFORE any external research.
 > Full doctrine: `arka/SKILL.md` (KB-First Research).
 <!-- arka:kb-first-prefix end -->
 

package/arka/skills/recipes/SKILL.md

@@ -14,8 +14,9 @@ allowed-tools: [Read, Bash]
 ---
 
 <!-- arka:kb-first-prefix begin -->
-> **KB-first:** query `mcp__obsidian__search_notes` and cite
-> `[[wikilinks]]` — or declare the gap — BEFORE any external research.
+> **KB-first:** query `mcp__obsidian__search_notes` (and
+> `mcp__graphify__query_graph` when configured) and cite `[[wikilinks]]`
+> or graph nodes — or declare the gap — BEFORE any external research.
 > Full doctrine: `arka/SKILL.md` (KB-First Research).
 <!-- arka:kb-first-prefix end -->
 

package/arka/skills/refine/SKILL.md

@@ -15,8 +15,9 @@ allowed-tools: [Read, AskUserQuestion, Skill]
 ---
 
 <!-- arka:kb-first-prefix begin -->
-> **KB-first:** query `mcp__obsidian__search_notes` and cite
-> `[[wikilinks]]` — or declare the gap — BEFORE any external research.
+> **KB-first:** query `mcp__obsidian__search_notes` (and
+> `mcp__graphify__query_graph` when configured) and cite `[[wikilinks]]`
+> or graph nodes — or declare the gap — BEFORE any external research.
 > Full doctrine: `arka/SKILL.md` (KB-First Research).
 <!-- arka:kb-first-prefix end -->
 

package/arka/skills/research/SKILL.md

@@ -17,8 +17,9 @@ allowed-tools: [Agent, Read, Write, mcp__obsidian__search_notes]
 ---
 
 <!-- arka:kb-first-prefix begin -->
-> **KB-first:** query `mcp__obsidian__search_notes` and cite
-> `[[wikilinks]]` — or declare the gap — BEFORE any external research.
+> **KB-first:** query `mcp__obsidian__search_notes` (and
+> `mcp__graphify__query_graph` when configured) and cite `[[wikilinks]]`
+> or graph nodes — or declare the gap — BEFORE any external research.
 > Full doctrine: `arka/SKILL.md` (KB-First Research).
 <!-- arka:kb-first-prefix end -->
 

package/bin/arka-doctor

@@ -3,6 +3,11 @@
 # ARKA OS — Doctor (Health Check System)
 # Usage: arka doctor [--fix] [--json]
 # 18 modular checks: fail = critical, warn = advisory
+#
+# SCOPE: this doctor audits the legacy v1 layout (~/.arka-os +
+# ~/.claude/skills). The CANONICAL doctor for the engine (venv, hooks,
+# fastpath, security advisory) is `npx arkaos doctor` — see issue #358
+# for the consolidation/migration map.
 # ============================================================================
 set -euo pipefail
 
@@ -421,4 +426,7 @@ else
     echo -e "  ${G}All checks passed!${N} ARKA OS is healthy."
   fi
   echo ""
+  echo -e "  ${C}Note:${N} this audits the legacy v1 layout (~/.arka-os + ~/.claude/skills)."
+  echo -e "  For the engine (venv, hooks, fastpath, security advisory) run: ${C}npx arkaos doctor${N}"
+  echo ""
 fi

package/core/cognition/insights/store.py

@@ -4,7 +4,9 @@ Persists ActionableInsight instances with support for status-based retrieval,
 project filtering, presentation lifecycle, and dismissal analytics.
 """
 
+import contextlib
 import sqlite3
+from collections.abc import Iterator
 from datetime import UTC, datetime
 from pathlib import Path
 
@@ -24,11 +26,20 @@ class InsightStore:
         self._db_path = db_path
         self._init_db()
 
-    def _conn(self) -> sqlite3.Connection:
+    @contextlib.contextmanager
+    def _conn(self) -> Iterator[sqlite3.Connection]:
+        """Per-operation connection: transaction semantics AND a real
+        close. ``with sqlite3.connect(...)`` alone only commits/rolls
+        back — it never closes, leaking one connection per operation
+        (ResourceWarning under coverage, amplified by ingest loops)."""
         conn = sqlite3.connect(self._db_path)
-        conn.row_factory = sqlite3.Row
-        conn.execute("PRAGMA journal_mode=WAL")
-        return conn
+        try:
+            conn.row_factory = sqlite3.Row
+            conn.execute("PRAGMA journal_mode=WAL")
+            with conn:
+                yield conn
+        finally:
+            conn.close()
 
     # Instinct columns added after the original 12-column schema. An
     # operator's existing DB has the old shape, so these are ALTER-added

package/core/forge/persistence.py

@@ -4,8 +4,9 @@ import os
 import re as _re
 from pathlib import Path
 from tempfile import NamedTemporaryFile
-from typing import Optional
+
 import yaml
+
 from core.forge.schema import ForgePlan, ForgeStatus
 
 
@@ -23,7 +24,9 @@ def save_plan(plan: ForgePlan) -> Path:
     plans.mkdir(parents=True, exist_ok=True)
     target = plans / f"{plan.id}.yaml"
     data = plan.model_dump(mode="json")
-    fd = NamedTemporaryFile(mode="w", dir=str(plans), suffix=".tmp", delete=False, encoding="utf-8")
+    fd = NamedTemporaryFile(  # noqa: SIM115 — handle outlives the block: os.replace consumes fd.name
+        mode="w", dir=str(plans), suffix=".tmp", delete=False, encoding="utf-8"
+    )
     try:
         yaml.dump(data, fd, default_flow_style=False, allow_unicode=True)
         fd.close()
@@ -35,7 +38,7 @@ def save_plan(plan: ForgePlan) -> Path:
     return target
 
 
-def load_plan(plan_id: str) -> Optional[ForgePlan]:
+def load_plan(plan_id: str) -> ForgePlan | None:
     """Load a forge plan by ID. Returns None if not found."""
     path = _plans_dir() / f"{plan_id}.yaml"
     if not path.exists():
@@ -54,12 +57,20 @@ def list_plans() -> list[dict]:
         if path.name == "active.yaml":
             continue
         data = yaml.safe_load(path.read_text(encoding="utf-8"))
+        if not isinstance(data, dict):
+            continue
+        # Pre-v4 plans stored complexity/critic as scalars — a summary
+        # must tolerate every shape that ever hit disk.
+        complexity = data.get("complexity")
+        critic = data.get("critic")
         results.append({
             "id": data.get("id", path.stem),
             "name": data.get("name", ""),
             "status": data.get("status", "draft"),
-            "tier": data.get("complexity", {}).get("tier", "shallow"),
-            "confidence": data.get("critic", {}).get("confidence", 0.0),
+            "tier": complexity.get("tier", "shallow")
+            if isinstance(complexity, dict) else "shallow",
+            "confidence": critic.get("confidence", 0.0)
+            if isinstance(critic, dict) else 0.0,
             "created_at": data.get("created_at", ""),
         })
     return results
@@ -72,7 +83,7 @@ def set_active_plan(plan_id: str) -> None:
     link.write_text(plan_id, encoding="utf-8")
 
 
-def get_active_plan() -> Optional[ForgePlan]:
+def get_active_plan() -> ForgePlan | None:
     """Get the currently active forge plan."""
     link = _active_link()
     if not link.exists():
@@ -94,7 +105,10 @@ def clear_active_plan() -> None:
 
 def _obsidian_forge_dir() -> Path:
     """Obsidian vault path for Forge documents."""
-    return Path.home() / "Documents" / "Personal" / "Projects" / "WizardingCode Internal" / "ArkaOS" / "Forge"
+    return (
+        Path.home() / "Documents" / "Personal" / "Projects"
+        / "WizardingCode Internal" / "ArkaOS" / "Forge"
+    )
 
 
 def export_to_obsidian(plan: ForgePlan) -> Path:
@@ -150,7 +164,8 @@ def _render_obsidian_context(plan: ForgePlan) -> list[str]:
     ctx = plan.context
     return [
         "## Context",
-        f"Repo: {ctx.repo} | Branch: {ctx.branch} | Commit: {ctx.commit_at_forge} | ArkaOS: {ctx.arkaos_version}",
+        f"Repo: {ctx.repo} | Branch: {ctx.branch} | "
+        f"Commit: {ctx.commit_at_forge} | ArkaOS: {ctx.arkaos_version}",
         "",
         "## Prompt",
         f"> {ctx.prompt}",
@@ -195,7 +210,10 @@ def _render_obsidian_critic(plan: ForgePlan) -> list[str]:
     if critic.risks:
         lines.append("### Risks")
         for risk in critic.risks:
-            lines.append(f"- **{risk.risk}** ({risk.severity.value}) — Mitigation: {risk.mitigation}")
+            lines.append(
+                f"- **{risk.risk}** ({risk.severity.value}) — "
+                f"Mitigation: {risk.mitigation}"
+            )
         lines.append("")
     return lines
 

package/core/forge/schema.py

@@ -6,23 +6,21 @@ structured ForgePlan that downstream agents consume.
 """
 
 from enum import Enum
-from typing import List, Optional
 
 from pydantic import BaseModel, Field, field_validator
 
-
 # ---------------------------------------------------------------------------
 # Enums
 # ---------------------------------------------------------------------------
 
-class ForgeTier(str, Enum):
+class ForgeTier(str, Enum):  # noqa: UP042 — StrEnum flips str()/format(); migration is its own change
     """Execution tier determined by complexity score."""
     SHALLOW = "shallow"
     STANDARD = "standard"
     DEEP = "deep"
 
 
-class ForgeStatus(str, Enum):
+class ForgeStatus(str, Enum):  # noqa: UP042 — StrEnum flips str()/format(); migration is its own change
     """Lifecycle status of a ForgePlan."""
     DRAFT = "draft"
     REVIEWING = "reviewing"
@@ -34,21 +32,21 @@ class ForgeStatus(str, Enum):
     ARCHIVED = "archived"
 
 
-class ExplorerLens(str, Enum):
+class ExplorerLens(str, Enum):  # noqa: UP042 — StrEnum flips str()/format(); migration is its own change
     """The analytical perspective used when exploring a plan."""
     PRAGMATIC = "pragmatic"          # Focus on fastest viable path
     ARCHITECTURAL = "architectural"  # Focus on long-term design health
     CONTRARIAN = "contrarian"        # Challenge assumptions, surface risks
 
 
-class RiskSeverity(str, Enum):
+class RiskSeverity(str, Enum):  # noqa: UP042 — StrEnum flips str()/format(); migration is its own change
     """Severity level for identified risks."""
     LOW = "low"
     MEDIUM = "medium"
     HIGH = "high"
 
 
-class ExecutionPathType(str, Enum):
+class ExecutionPathType(str, Enum):  # noqa: UP042 — StrEnum flips str()/format(); migration is its own change
     """Type of execution artefact that fulfils a plan step."""
     SKILL = "skill"
     WORKFLOW = "workflow"
@@ -60,12 +58,22 @@ class ExecutionPathType(str, Enum):
 # ---------------------------------------------------------------------------
 
 class ComplexityDimensions(BaseModel):
-    """Five-axis complexity breakdown, each scored 0–100."""
+    """Five-axis complexity breakdown, each scored 0-100."""
 
-    scope: int = Field(default=0, description="Breadth of change across the codebase or system.")
-    dependencies: int = Field(default=0, description="Number and criticality of upstream/downstream dependencies.")
-    ambiguity: int = Field(default=0, description="How unclear or under-specified the requirements are.")
-    risk: int = Field(default=0, description="Potential for breakage, data loss, or security impact.")
+    scope: int = Field(
+        default=0, description="Breadth of change across the codebase or system."
+    )
+    dependencies: int = Field(
+        default=0,
+        description="Number and criticality of upstream/downstream dependencies.",
+    )
+    ambiguity: int = Field(
+        default=0, description="How unclear or under-specified the requirements are."
+    )
+    risk: int = Field(
+        default=0,
+        description="Potential for breakage, data loss, or security impact.",
+    )
     novelty: int = Field(default=0, description="How unlike existing patterns this work is.")
 
     @field_validator("scope", "dependencies", "ambiguity", "risk", "novelty", mode="before")
@@ -78,14 +86,19 @@ class ComplexityDimensions(BaseModel):
 class ComplexityScore(BaseModel):
     """Aggregated complexity result produced by the Complexity Scorer."""
 
-    score: int = Field(default=0, description="Composite 0–100 score derived from all dimensions.")
-    tier: ForgeTier = Field(default=ForgeTier.SHALLOW, description="Execution tier selected based on the composite score.")
-    dimensions: ComplexityDimensions = Field(default_factory=ComplexityDimensions, description="Per-dimension breakdown.")
-    similar_plans: List[str] = Field(
+    score: int = Field(default=0, description="Composite 0-100 score derived from all dimensions.")
+    tier: ForgeTier = Field(
+        default=ForgeTier.SHALLOW,
+        description="Execution tier selected based on the composite score.",
+    )
+    dimensions: ComplexityDimensions = Field(
+        default_factory=ComplexityDimensions, description="Per-dimension breakdown."
+    )
+    similar_plans: list[str] = Field(
         default_factory=list,
         description="IDs of previously completed plans with similar profiles.",
     )
-    reused_patterns: List[str] = Field(
+    reused_patterns: list[str] = Field(
         default_factory=list,
         description="Named patterns from the ArkaOS pattern library reused in this plan.",
     )
@@ -213,13 +226,23 @@ class ForgePlan(BaseModel):
             "contains only constitution-enforced phases and confidence is 0.0."
         ),
     )
-    dispatch_errors: List[str] = Field(
+    dispatch_errors: list[str] = Field(
         default_factory=list,
         description="Dispatch failures collected during forge (lens: error class: message).",
     )
 
     status: ForgeStatus = ForgeStatus.DRAFT
-    approved_at: Optional[str] = None
-    approved_by: Optional[str] = None
-    executed_at: Optional[str] = None
-    completion_notes: Optional[str] = None
+    approved_at: str | None = None
+    approved_by: str | None = None
+    rejected_at: str | None = None
+    rejected_by: str | None = None
+    executed_at: str | None = None
+    completion_notes: str | None = None
+    review_note: str | None = Field(
+        default=None,
+        description=(
+            "Operator note attached at decision time (plan-canvas review) "
+            "— the 'ponto-e-anota' trail; distinct from completion_notes, "
+            "which belongs to execution."
+        ),
+    )