arkaos 4.0.2 → 4.1.0

package/dashboard/app/pages/knowledge/index.vue

@@ -594,7 +594,10 @@ async function handleSearch() {
   }
 }
 
-function formatScore(score: number): string {
+// RAG honesty (PR-3 v4.1): keyword-degraded results carry score=null —
+// there is no similarity to show, so label them instead of faking "0%".
+function formatScore(score: number | null): string {
+  if (score === null || score === undefined) return 'keyword match'
   return `${(score * 100).toFixed(0)}%`
 }
 

package/departments/ops/skills/n8n-flow/SKILL.md

@@ -27,6 +27,19 @@ does not replace the vault.
 
 n8n workflow design: AI nodes, webhooks, branching, error handling.
 
+## Event-driven watching (Monitor)
+
+When validating a deployed flow, prefer the runtime's Monitor tool over
+polling loops — zero idle tokens versus a model turn per interval.
+
+```
+Monitor: watch the n8n execution log (or webhook endpoint output) until
+/error|failed|succeeded/ matches, then inspect that execution and report.
+```
+
+Fallback: on runtimes without Monitor, use a wide-interval `/loop` and
+stop it as soon as the first relevant event lands.
+
 ## Output
 
 n8n flow spec with node configuration and AI integration points

package/departments/ops/skills/workflow-automate/SKILL.md

@@ -71,4 +71,20 @@ Follow the [Computer Use Availability Check](/arka) for availability checking.
 /schedule hourly — monitor all active automations and report error rate
 ```
 
+## Event-driven watching (Monitor)
+
+Prefer the runtime's Monitor tool over polling loops — it blocks on a
+condition and burns zero idle tokens, while `/loop` re-invokes the model
+every interval even when nothing changed.
+
+Pattern (watch logs, act on first match):
+
+```
+Monitor: tail the automation log until /ERROR|failed/ matches,
+then diagnose that execution and alert the operator.
+```
+
+Use polling (`/loop`) only as fallback on runtimes without Monitor, and
+pick the widest interval the SLA tolerates.
+
 ## Output → Workflow diagram + platform config + error handling spec

package/departments/quality/SKILL.md

@@ -15,19 +15,55 @@ allowed-tools: [Read, Write, Edit, Bash, Grep, Glob, Agent]
 The Quality Gate is NOT invoked by the user directly. It runs automatically as the
 second-to-last phase of EVERY workflow in EVERY department.
 
+The gate is EVIDENCE INTERPRETATION, not persona role-play. The verdict DERIVES
+from executable check output; reviewers interpret the report, they never
+override it with narrative.
+
 ```
 Any Department Workflow:
   ...
   Phase N-1: QUALITY GATE
-    1. Marta receives ALL output from execution phases
-    2. Marta dispatches Eduardo (text) + Francisca (tech) in parallel
-    3. Each reviewer returns APPROVED or REJECTED with specific issues
-    4. If ANY reviewer rejects → work loops back with issue list
+    1. Run the evidence engine over the project/diff:
+         python -m core.governance.evidence_checks <project_dir> \
+           [--changed-files f1,f2] [--test-command '...'] --json
+    2. Marta dispatches Eduardo + Francisca to INTERPRET the report:
+       - Eduardo: spellcheck section + prose review of changed copy
+       - Francisca: lint / typecheck / tests / coverage / security-grep
+    3. Verdict rules (binary, evidence-floored):
+       - overall == "fail"  → REJECTED. Always. No persona can override
+         failing evidence with narrative.
+       - overall == "pass"  → APPROVED only if reviewers find no blocker
+         the checks cannot see (logic, copy, UX).
+       - overall == "insufficient-evidence" → APPROVED only with an
+         explicit justification in the verdict notes; otherwise REJECTED.
+    4. If ANY reviewer rejects → work loops back with the blockers list
     5. If ALL approve → Marta issues final APPROVED verdict
   Phase N: DELIVERY
     → Only reaches user after APPROVED from all three
 ```
 
+## Reviewer Dispatch Contract
+
+Reviewers are dispatched via the Agent tool with STRUCTURED OUTPUT. The output
+schema is `QG_VERDICT_JSON_SCHEMA` from `core.governance.qg_verdict` (the JSON
+Schema of the `QGVerdict` pydantic model):
+
+    from core.governance.qg_verdict import QG_VERDICT_JSON_SCHEMA
+
+    Agent(
+        subagent_type="francisca-tech",       # .claude/agents/francisca-tech.md
+        model="sonnet",                        # opus ONLY for Tier 0/security scope
+        prompt="<evidence report JSON> + <diff summary> — interpret and return QGVerdict",
+        output_schema=QG_VERDICT_JSON_SCHEMA,  # structured-output param
+    )
+
+Each reviewer MUST return a `QGVerdict` JSON object: `verdict`
+(APPROVED|REJECTED), `evidence_report` (embedded summary), `blockers`
+(`[{check, detail, file}]`), `reviewer`, `model_used`, `notes`. The pydantic
+model rejects APPROVED-with-failing-evidence at validation time, and
+`core.governance.review_workflow` raises `ValueError` on any attempt to record
+an approval over `evidence_overall == "fail"`.
+
 ## Squad
 
 | Agent | Role | Tier | DISC | Scope |
@@ -70,7 +106,11 @@ There is no "APPROVED WITH CAVEATS". It's binary. Fix issues first.
 When dispatching subagent work via the Task tool, include the `model` parameter from the target agent's YAML `model:` field:
 
 - Agent YAMLs at `departments/*/agents/*.yaml` have `model: opus | sonnet | haiku`
-- Quality Gate dispatch (Marta/Eduardo/Francisca) ALWAYS uses `model: opus` — NON-NEGOTIABLE
+- Quality Gate reviewers (Eduardo/Francisca) run on `sonnet` by DEFAULT.
+  `opus` is used ONLY when the diff is Tier 0 scope (constitution, security,
+  release pipeline, installer auth) or the deliverable is security-flagged.
+- Marta keeps her veto regardless of the model tier the review ran on —
+  the verdict derives from evidence, not from model size.
 - Default to `sonnet` if the agent YAML has no `model` field
 - Mechanical tasks (commit messages, routing, keyword extraction) use `model: haiku`
 

package/departments/quality/agents/copy-director.yaml

@@ -3,7 +3,9 @@ name: Eduardo
 role: Copy & Language Director
 department: quality
 tier: 0
-model: opus
+# PR-4 evidence QG (v4.1): reviewers run sonnet by default; dispatch on
+# opus ONLY for Tier 0/security-scope diffs (see constitution model-routing).
+model: sonnet
 
 behavioral_dna:
   disc:

package/departments/quality/agents/tech-director.yaml

@@ -3,7 +3,9 @@ name: Francisca
 role: Technical & UX Quality Director
 department: quality
 tier: 0
-model: opus
+# PR-4 evidence QG (v4.1): reviewers run sonnet by default; dispatch on
+# opus ONLY for Tier 0/security-scope diffs (see constitution model-routing).
+model: sonnet
 
 behavioral_dna:
   disc:

package/installer/adapters/claude-code.js

@@ -1,8 +1,52 @@
-import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
-import { join, dirname } from "node:path";
+import { existsSync, readFileSync, writeFileSync, mkdirSync, readdirSync, copyFileSync, statSync } from "node:fs";
+import { join, dirname, resolve } from "node:path";
 import { platform } from "node:os";
+import { fileURLToPath } from "node:url";
 
 const IS_WINDOWS = platform() === "win32";
+const ARKAOS_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..", "..");
+
+/**
+ * Deploy the packaged Quality Gate / squad-lead subagent definitions
+ * (`config/claude-agents/*.md` in the ArkaOS package: marta-cqo,
+ * eduardo-copy, francisca-tech, paulo-tech-lead) into a project's
+ * `.claude/agents/` directory, so Claude Code can dispatch them as real
+ * subagent types with structured QGVerdict output (PR-4 evidence
+ * Quality Gate). Source lives under config/ because `.claude/` is
+ * gitignored in the ArkaOS repo itself.
+ *
+ * Same merge philosophy as configureHooks: never delete user files,
+ * overwrite only the ArkaOS-owned definitions by name. Best-effort —
+ * a missing source dir (older package) is a silent no-op.
+ *
+ * @param {string} projectDir - project root (contains or gets .claude/)
+ * @param {string} [sourceRoot] - override for tests; defaults to package root
+ * @returns {number} count of agent definitions deployed
+ */
+export function deployProjectAgents(projectDir, sourceRoot = ARKAOS_ROOT) {
+  const agentsSrc = join(sourceRoot, "config", "claude-agents");
+  if (!existsSync(agentsSrc)) return 0;
+
+  const agentsDest = join(projectDir, ".claude", "agents");
+  let deployed = 0;
+  try {
+    mkdirSync(agentsDest, { recursive: true });
+    for (const file of readdirSync(agentsSrc)) {
+      if (!file.endsWith(".md")) continue;
+      const srcFile = join(agentsSrc, file);
+      try {
+        if (!statSync(srcFile).isFile()) continue;
+        copyFileSync(srcFile, join(agentsDest, file));
+        deployed++;
+      } catch {
+        // Best-effort — a single unreadable agent file shouldn't break init.
+      }
+    }
+  } catch {
+    return deployed;
+  }
+  return deployed;
+}
 
 /**
  * Build a complete inner hook-entry object for Claude Code's settings.json.

package/installer/config-seed.js

@@ -1,13 +1,19 @@
-// ~/.arkaos/config.json seed/migration (PR19 v2.41.0).
+// ~/.arkaos/config.json seed/migration (PR19 v2.41.0, extended PR-3 v4.1).
 //
 // Run on every `npx arkaos install` and `npx arkaos@latest update`.
-// Idempotent: writes `hooks.hardEnforcement = true` only when the key
-// is unset. Explicit user choice (true OR false) is preserved.
+// Idempotent: seeds each template key only when it is unset. Explicit
+// user choice (true OR false) is always preserved.
+//
+// Seeded template keys (operator decisions):
+//   hooks.hardEnforcement = true   (PR19 v2.41.0)
+//   hooks.kbFirst         = true   (PR-3 v4.1 — KB-first ON out of the box)
 //
 // Returns a status object:
 //   { action: "created" | "added-key" | "noop"
 //          | "preserved-user-false" | "rewrote-corrupt" }
 // so the installer caller can log a human-readable line per run.
+// Precedence when several keys differ: created/rewrote-corrupt >
+// added-key > preserved-user-false > noop.
 
 import {
   existsSync, mkdirSync, readFileSync, writeFileSync, renameSync, copyFileSync,
@@ -15,11 +21,20 @@ import {
 import { homedir } from "node:os";
 import { join, dirname } from "node:path";
 
+// Template: every hooks.* key seeded to `true` when unset.
+const SEEDED_HOOK_KEYS = ["hardEnforcement", "kbFirst"];
+
+function defaultConfig() {
+  const hooks = {};
+  for (const key of SEEDED_HOOK_KEYS) hooks[key] = true;
+  return { hooks };
+}
+
 export function seedArkaosConfig({ home = homedir() } = {}) {
   const cfgPath = join(home, ".arkaos", "config.json");
 
   if (!existsSync(cfgPath)) {
-    writeConfig(cfgPath, { hooks: { hardEnforcement: true } });
+    writeConfig(cfgPath, defaultConfig());
     return { action: "created", path: cfgPath };
   }
 
@@ -33,24 +48,34 @@ export function seedArkaosConfig({ home = homedir() } = {}) {
     // Corrupt JSON — keep the broken copy for recovery, write safe default.
     const backup = `${cfgPath}.broken-${Date.now()}`;
     try { copyFileSync(cfgPath, backup); } catch { /* best effort */ }
-    writeConfig(cfgPath, { hooks: { hardEnforcement: true } });
+    writeConfig(cfgPath, defaultConfig());
     return { action: "rewrote-corrupt", path: cfgPath, backup };
   }
 
   config.hooks = config.hooks && typeof config.hooks === "object" ? config.hooks : {};
-  const current = config.hooks.hardEnforcement;
 
-  if (current === true) {
-    return { action: "noop", path: cfgPath };
+  let added = false;
+  let preservedFalse = false;
+  for (const key of SEEDED_HOOK_KEYS) {
+    const current = config.hooks[key];
+    if (current === true) continue;
+    if (current === false) {
+      preservedFalse = true; // explicit user choice — never overwrite
+      continue;
+    }
+    // Key unset (undefined, null, or any non-boolean) — set to true.
+    config.hooks[key] = true;
+    added = true;
+  }
+
+  if (added) {
+    writeConfig(cfgPath, config);
+    return { action: "added-key", path: cfgPath };
   }
-  if (current === false) {
+  if (preservedFalse) {
     return { action: "preserved-user-false", path: cfgPath };
   }
-
-  // Key unset (undefined, null, or any non-boolean) — set to true.
-  config.hooks.hardEnforcement = true;
-  writeConfig(cfgPath, config);
-  return { action: "added-key", path: cfgPath };
+  return { action: "noop", path: cfgPath };
 }
 
 function writeConfig(cfgPath, payload) {

package/installer/doctor.js

@@ -5,6 +5,7 @@ import { execSync } from "node:child_process";
 import { getArkaosPython, getVenvPython, canImportCore, getRepoRoot, diagnoseVenv, ensureVenvHealthy } from "./python-resolver.js";
 import { IS_WINDOWS, HOOK_EXT, CMD_FINDER } from "./platform.js";
 import { checkNode, checkObsidian, checkOllama } from "./system-tools.js";
+import { graphifyDoctor } from "./graphify.js";
 
 const INSTALL_DIR = join(homedir(), ".arkaos");
 
@@ -195,6 +196,13 @@ const checks = [
     },
     fix: () => "Upgrade Claude Code: npm install -g @anthropic-ai/claude-code@latest",
   },
+  {
+    name: "graphify",
+    description: "Graphify CLI present (grounding layer — code knowledge graphs)",
+    severity: "warn",
+    check: () => graphifyDoctor().installed,
+    fix: () => graphifyDoctor().hint || "Run: uv tool install graphifyy  (or pipx install graphifyy)",
+  },
   {
     name: "magic-api-key",
     description: "Magic API key configured (frontend UI/UX — Magic MCP)",

package/installer/graphify.js

@@ -0,0 +1,153 @@
+// Graphify — code knowledge-graph grounding layer for `npx arkaos install`
+// and `npx arkaos@latest update`.
+//
+// Graphify (PyPI package `graphifyy`, CLI `graphify`) extracts a local
+// tree-sitter code graph into `<project>/graphify-out/graph.json` with
+// EXTRACTED/INFERRED/AMBIGUOUS confidence tags. ArkaOS uses that graph as
+// the official grounding layer (Synapse L2.7) so answers about a codebase
+// cite real nodes + source locations instead of inventing structure.
+//
+// Install strategy (best-effort, in order):
+//   1. `graphify` already on PATH             → no-op.
+//   2. `uv tool install graphifyy`  (preferred)
+//   3. `pipx install graphifyy`     (fallback)
+//   4. Neither manager available   → print a one-line manual hint.
+// Then `graphify install` registers the Graphify skill with AI assistants
+// (same best-effort tolerance).
+//
+// Invariants (.claude/rules/node-installer.md):
+//   - ESM, os.homedir()/path.join only, never hardcoded paths.
+//   - No interactive prompts; safe in headless/CI runs.
+//   - Never throws — the installer must NEVER fail because of Graphify.
+
+import { execSync, spawnSync } from "node:child_process";
+import { CMD_FINDER } from "./platform.js";
+
+const PYPI_PACKAGE = "graphifyy"; // double y — the CLI binary is `graphify`
+const MANUAL_HINT =
+  "Graphify not installed — install manually: uv tool install graphifyy (or pipx install graphifyy)";
+
+function findBinary(name) {
+  try {
+    const out = execSync(`${CMD_FINDER} ${name}`, {
+      stdio: ["ignore", "pipe", "ignore"],
+    }).toString().trim().split(/\r?\n/)[0];
+    return out || null;
+  } catch {
+    return null;
+  }
+}
+
+function readVersion(command) {
+  try {
+    const out = execSync(command, { stdio: ["ignore", "pipe", "ignore"] }).toString();
+    const match = out.match(/(\d+\.\d+(?:\.\d+)?)/);
+    return match ? match[1] : null;
+  } catch {
+    return null;
+  }
+}
+
+// Try one package-manager install of `graphifyy`. Returns true when the
+// child exited 0. Never throws.
+function tryInstallVia(manager) {
+  const args = manager === "uv" ? ["tool", "install", PYPI_PACKAGE] : ["install", PYPI_PACKAGE];
+  const out = spawnSync(manager, args, {
+    timeout: 180_000,
+    stdio: ["ignore", "pipe", "pipe"],
+    encoding: "utf-8",
+  });
+  return !out.error && out.status === 0;
+}
+
+// Run `graphify install` so the Graphify skill registers with the AI
+// assistant runtimes it detects. Best-effort: failure is reported in the
+// status object, never thrown.
+function runGraphifySkillInstall() {
+  const out = spawnSync("graphify", ["install"], {
+    timeout: 60_000,
+    stdio: ["ignore", "pipe", "pipe"],
+    encoding: "utf-8",
+  });
+  if (out.error || out.status !== 0) {
+    const reason = (out.stderr || out.error?.message || "unknown").trim().slice(0, 200);
+    return { action: "failed", reason };
+  }
+  return { action: "installed" };
+}
+
+/**
+ * Ensure the Graphify CLI is present and its skill is registered.
+ *
+ * Returns a status object — never throws, never blocks the install:
+ *   { binary: { installed, location?, version?, action, hint? },
+ *     skillInstall: { action, reason? } }
+ *
+ * `options.dryRun` skips installation attempts and `graphify install`.
+ */
+export function ensureGraphify(options = {}) {
+  const result = { binary: null, skillInstall: { action: "skipped", reason: "binary-missing" } };
+  try {
+    let location = findBinary("graphify");
+
+    if (!location && !options.dryRun) {
+      if (findBinary("uv") && tryInstallVia("uv")) {
+        location = findBinary("graphify");
+      } else if (findBinary("pipx") && tryInstallVia("pipx")) {
+        location = findBinary("graphify");
+      }
+    }
+
+    if (!location) {
+      result.binary = {
+        installed: false,
+        action: options.dryRun ? "dry-run" : "manual-install-needed",
+        hint: MANUAL_HINT,
+      };
+      return result;
+    }
+
+    result.binary = {
+      installed: true,
+      location,
+      version: readVersion("graphify --version"),
+      action: "present",
+    };
+
+    if (options.dryRun) {
+      result.skillInstall = { action: "skipped", reason: "dry-run" };
+    } else {
+      result.skillInstall = runGraphifySkillInstall();
+    }
+    return result;
+  } catch (err) {
+    result.binary = result.binary || {
+      installed: false,
+      action: "check-failed",
+      hint: MANUAL_HINT,
+    };
+    result.skillInstall = { action: "failed", reason: err.message };
+    return result;
+  }
+}
+
+/**
+ * Doctor check for installer/doctor.js — is the `graphify` binary present,
+ * and at which version? Never throws.
+ */
+export function graphifyDoctor() {
+  try {
+    const location = findBinary("graphify");
+    if (!location) {
+      return { installed: false, location: null, version: null, hint: MANUAL_HINT };
+    }
+    return {
+      installed: true,
+      location,
+      version: readVersion("graphify --version"),
+      hint: null,
+    };
+  } catch {
+    return { installed: false, location: null, version: null, hint: MANUAL_HINT };
+  }
+}

package/installer/index.js

@@ -394,6 +394,26 @@ export async function install({ runtime, path, force, skipSystem, withOllama })
     console.log(`         Warning: could not set up frontend tooling (${err.message})`);
   }
 
+  // Graphify grounding layer — code knowledge graphs (PyPI `graphifyy`,
+  // CLI `graphify`). Best-effort: a missing binary or failed install can
+  // NEVER fail `npx arkaos install`; we degrade to a one-line hint.
+  try {
+    const { ensureGraphify } = await import("./graphify.js");
+    const gf = ensureGraphify();
+    if (gf.binary?.installed) {
+      console.log(`         Graphify ready${gf.binary.version ? ` (v${gf.binary.version})` : ""}.`);
+      if (gf.skillInstall?.action === "installed") {
+        console.log("         Graphify skill registered (graphify install).");
+      } else if (gf.skillInstall?.action === "failed") {
+        console.log(`         Graphify skill registration failed (${gf.skillInstall.reason}).`);
+      }
+    } else if (gf.binary?.hint) {
+      console.log(`         ${gf.binary.hint}`);
+    }
+  } catch (err) {
+    console.log(`         Warning: could not set up Graphify (${err.message})`);
+  }
+
   const manifest = {
     version: VERSION,
     runtime,

package/installer/init.js

@@ -56,6 +56,17 @@ export async function init({ path }) {
     console.log(`  Created: .claude/settings.local.json`);
   }
 
+  // Deploy Quality Gate / squad-lead subagent definitions (.claude/agents/)
+  try {
+    const { deployProjectAgents } = await import("./adapters/claude-code.js");
+    const agentCount = deployProjectAgents(projectDir);
+    if (agentCount > 0) {
+      console.log(`  Created: .claude/agents/ (${agentCount} subagent definitions)`);
+    }
+  } catch {
+    // Best-effort — init must not fail on optional agent deployment.
+  }
+
   console.log(`
   Project initialized for ArkaOS.
 

package/installer/update.js

@@ -478,6 +478,25 @@ export async function update() {
     console.log(`         ⚠ Could not set up frontend tooling (${err.message})`);
   }
 
+  // Graphify grounding layer — same wiring as installer/index.js. Best
+  // effort: `npx arkaos update` never fails because of Graphify.
+  try {
+    const { ensureGraphify } = await import("./graphify.js");
+    const gf = ensureGraphify();
+    if (gf.binary?.installed) {
+      console.log(`         ✓ Graphify ready${gf.binary.version ? ` (v${gf.binary.version})` : ""}`);
+      if (gf.skillInstall?.action === "installed") {
+        console.log("         ✓ Graphify skill registered (graphify install)");
+      } else if (gf.skillInstall?.action === "failed") {
+        console.log(`         ⚠ Graphify skill registration failed (${gf.skillInstall.reason})`);
+      }
+    } else if (gf.binary?.hint) {
+      console.log(`         ⚠ ${gf.binary.hint}`);
+    }
+  } catch (err) {
+    console.log(`         ⚠ Could not set up Graphify (${err.message})`);
+  }
+
   // ── 8. Update manifest ──
   console.log("  [8/8] Finalizing...");
   manifest.version = VERSION;

package/package.json

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

package/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "arkaos-core"
-version = "4.0.2"
+version = "4.1.0"
 description = "Core engine for ArkaOS — The Operating System for AI Agent Teams"
 readme = "README.md"
 license = {text = "MIT"}

package/scripts/knowledge-index.py

@@ -49,7 +49,8 @@ def main() -> int:
         else:
             print(f"Chunks:     {stats['total_chunks']}")
             print(f"Files:      {stats['total_files']}")
-            print(f"VSS:        {'enabled' if stats['vss_available'] else 'disabled (keyword fallback)'}")
+            print(f"Retrieval:  {stats.get('retrieval_mode', 'unknown')}")
+            print(f"Vec:        {'enabled' if stats.get('vec_available') else 'disabled (keyword fallback)'}")
             print(f"DB:         {stats['db_path']}")
         return 0
 
@@ -62,7 +63,12 @@ def main() -> int:
                 print("No results found.")
             for i, r in enumerate(results, 1):
                 src = Path(r.get("source", "")).name if r.get("source") else "unknown"
-                print(f"\n[{i}] Score: {r['score']:.3f} | {src}")
+                # RAG honesty: degraded keyword matches have NO similarity
+                # score — never print one.
+                if r.get("score") is None:
+                    print(f"\n[{i}] Match: keyword-degraded (no similarity) | {src}")
+                else:
+                    print(f"\n[{i}] Score: {r['score']:.3f} | {src}")
                 if r.get("heading"):
                     print(f"    Heading: {r['heading']}")
                 print(f"    {r['text'][:200]}...")