arkaos 4.21.0 → 4.23.0

package/README.md

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

package/THE-ARKAOS-GUIDE.md

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

package/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/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/config/claude-agents/marta-cqo.md

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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