arkaos 4.23.0 → 4.25.0

package/installer/doctor.js

@@ -48,6 +48,106 @@ export function corruptDbBackups(baseDir = INSTALL_DIR) {
   }
 }
 
+// ─── Claude-layer probes (issue #358 migration) ─────────────────────────
+// Migrated from the retired bash doctor's Claude-skills layer. Paths are
+// injectable for tests. Three bash checks were deliberately NOT migrated
+// because they audit v1-only artifacts with no v2 counterpart:
+//   personas      — v2 deploys agents per-project via the sync engine
+//   agent-memory  — superseded by the claude-mem plugin
+//   capabilities  — v1 KB artifact (~/.arka-os/capabilities.json)
+
+// The hook FILES living in ~/.arkaos/config/hooks (the hooks-dir check)
+// prove nothing about whether Claude Code RUNS them. Governance is only
+// live when ~/.claude/settings.json references the chain — a machine can
+// have every script present, nothing wired, and a green doctor.
+export function hooksWired(
+  settingsPath = join(homedir(), ".claude", "settings.json")
+) {
+  if (!existsSync(settingsPath)) return true; // no Claude Code — not applicable
+  try {
+    const settings = JSON.parse(readFileSync(settingsPath, "utf-8"));
+    return !!(settings.hooks && settings.hooks.UserPromptSubmit);
+  } catch {
+    return false; // unreadable settings = unverifiable wiring, surface it
+  }
+}
+
+// Status line: configured AND the command it points at exists on disk.
+export function statuslineConfigured(
+  settingsPath = join(homedir(), ".claude", "settings.json")
+) {
+  if (!existsSync(settingsPath)) return true; // no Claude Code — not applicable
+  try {
+    const settings = JSON.parse(readFileSync(settingsPath, "utf-8"));
+    const cmd = settings.statusLine && settings.statusLine.command;
+    if (!cmd) return false;
+    return existsSync(cmd);
+  } catch {
+    return false;
+  }
+}
+
+// gotchas.json is live v2 state: capture/collector.py appends to it and
+// `/arka evolve` (#348) ingests it. Missing means capture never ran;
+// corrupt means evolve will choke.
+export function gotchasHealthy(
+  gotchasPath = join(INSTALL_DIR, "gotchas.json")
+) {
+  if (!existsSync(gotchasPath)) return false;
+  try {
+    return Array.isArray(JSON.parse(readFileSync(gotchasPath, "utf-8")));
+  } catch {
+    return false;
+  }
+}
+
+// The MCP registry ships inside the read-only arka skill bundle.
+export function mcpRegistryHealthy(
+  registryPath = join(
+    homedir(), ".claude", "skills", "arka", "mcps", "registry.json")
+) {
+  if (!existsSync(registryPath)) return false;
+  try {
+    const reg = JSON.parse(readFileSync(registryPath, "utf-8"));
+    return !!reg.mcpServers;
+  } catch {
+    return false;
+  }
+}
+
+// Floor for "an ArkaOS skill set is deployed at all" — curated mode
+// ships 37 core skills, so 7 is a deliberately low absence detector,
+// not a completeness gauge (skills-surface judges completeness).
+export function deployedSkillCount(
+  skillsDir = join(homedir(), ".claude", "skills")
+) {
+  try {
+    return readdirSync(skillsDir).filter(
+      (dir) =>
+        dir.startsWith("arka-") &&
+        existsSync(join(skillsDir, dir, "SKILL.md"))
+    ).length;
+  } catch {
+    return 0;
+  }
+}
+
+// Recommended companion plugins (Superpowers + Claude-Mem). Probing
+// spawns the claude CLI, so keep a hard timeout — a hung CLI must not
+// stall the doctor (same rule as arka-tools-runner).
+export function companionPluginsInstalled() {
+  if (!commandExists("claude")) return true; // no Claude Code — not applicable
+  try {
+    const out = execSync("claude plugin list", {
+      stdio: ["pipe", "pipe", "ignore"],
+      timeout: 15000,
+    }).toString();
+    return out.includes("superpowers") && out.includes("claude-mem");
+  } catch {
+    return false;
+  }
+}
+
 export const checks = [
   {
     name: "install-dir",
@@ -405,6 +505,80 @@ export const checks = [
     },
     fix: () => "Run: npx arkaos keys set HIGGSFIELD_API_KEY <key> (https://higgsfield.ai) — needed for Higgsfield MCP generation",
   },
+  // ─── Claude-layer checks (issue #358) — migrated from the bash doctor.
+  // All warn-only: ArkaOS is multi-runtime, so absence of the Claude
+  // surface must never fail an install that targets codex/gemini/cursor.
+  {
+    name: "claude-cli",
+    description: "Claude Code CLI installed",
+    severity: "warn",
+    check: () => commandExists("claude"),
+    fix: () => "Install: npm install -g @anthropic-ai/claude-code (or use another supported runtime)",
+  },
+  {
+    name: "arka-skill",
+    description: "arka orchestrator skill bundle deployed (~/.claude/skills/arka)",
+    severity: "warn",
+    check: () =>
+      existsSync(join(homedir(), ".claude", "skills", "arka", "SKILL.md")),
+    fix: () => "Run: npx arkaos install --force",
+  },
+  {
+    name: "jq",
+    description: "jq available (bash hooks parse JSON with it; python3 is the fallback)",
+    severity: "warn",
+    check: () => commandExists("jq"),
+    fix: () => "Install jq: brew install jq (macOS) / apt install jq (Linux)",
+  },
+  {
+    name: "statusline",
+    description: "Status line configured and its command exists",
+    severity: "warn",
+    check: () => statuslineConfigured(),
+    fix: () => "Run: npx arkaos install --force (redeploys and wires the statusline)",
+  },
+  {
+    name: "hooks-wired",
+    description: "Hook chain referenced by ~/.claude/settings.json (governance live)",
+    severity: "warn",
+    check: () => hooksWired(),
+    fix: () => "Run: npx arkaos install --force (rewires hooks into settings.json)",
+  },
+  {
+    name: "skills-deployed",
+    description: "ArkaOS skill set deployed (>= 7 arka-* skills)",
+    severity: "warn",
+    check: () => deployedSkillCount() >= 7,
+    fix: () => "Run: npx arkaos@latest update (redeploys the curated skill set)",
+  },
+  {
+    name: "mcp-registry",
+    description: "MCP registry present in the arka skill bundle",
+    severity: "warn",
+    check: () => mcpRegistryHealthy(),
+    fix: () => "Run: npx arkaos install --force",
+  },
+  {
+    name: "yt-dlp",
+    description: "yt-dlp present (video reference analysis + content ingestion)",
+    severity: "warn",
+    check: () => commandExists("yt-dlp"),
+    fix: () => "Install yt-dlp: brew install yt-dlp (macOS) / pipx install yt-dlp — only needed for video/content workflows",
+  },
+  {
+    name: "gotchas",
+    description: "gotchas.json valid (capture layer output, ingested by /arka evolve)",
+    severity: "warn",
+    check: () => gotchasHealthy(),
+    fix: () => "Missing: capture has not run yet (created automatically). Corrupt: inspect ~/.arkaos/gotchas.json — /arka evolve cannot ingest it",
+  },
+  {
+    name: "companion-plugins",
+    description: "Companion plugins installed (Superpowers + Claude-Mem)",
+    severity: "warn",
+    check: () => companionPluginsInstalled(),
+    fix: () => "claude plugin marketplace add obra/superpowers-marketplace && claude plugin install superpowers@superpowers-marketplace; claude plugin marketplace add thedotmack/claude-mem && claude plugin install claude-mem@thedotmack",
+  },
 ];
 
 // ─── Windows-only checks ───────────────────────────────────────────────
@@ -464,6 +638,8 @@ if (IS_WINDOWS) {
 
 export async function doctor(options = {}) {
   const fixMode = !!options.fix;
+  const jsonMode = !!options.json;
+  if (jsonMode) return doctorJson();
   console.log(`\n  ArkaOS Doctor — Health Checks${fixMode ? " (--fix)" : ""}\n`);
 
   // ─── --fix: repair the venv before reporting checks (PR2 v3.73.1) ────
@@ -535,6 +711,54 @@ export async function doctor(options = {}) {
   if (failed > 0) process.exit(1);
 }
 
+// Machine-readable run (issue #358 step 4). Same checks, same exit-code
+// contract as the human run; the security advisory stays out — it is a
+// human-facing print, and the scanner already has its own --json
+// (core.governance.harness_scanner_cli).
+function doctorJson() {
+  const results = [];
+  let passed = 0;
+  let warned = 0;
+  let failed = 0;
+  for (const check of checks) {
+    let ok = false;
+    let error = null;
+    try {
+      ok = !!check.check();
+    } catch (err) {
+      error = err && err.message
+        ? String(err.message).split("\n")[0].slice(0, 120)
+        : String(err);
+    }
+    const status = ok ? "pass" : check.severity === "fail" ? "fail" : "warn";
+    if (ok) passed++;
+    else if (check.severity === "fail") failed++;
+    else warned++;
+    const entry = {
+      name: check.name,
+      status,
+      severity: check.severity,
+      description: check.description,
+      fix: ok ? "" : safeFix(check),
+    };
+    if (error) entry.error = error;
+    results.push(entry);
+  }
+  console.log(JSON.stringify({
+    checks: results,
+    summary: { passed, warned, failed, total: results.length },
+  }));
+  if (failed > 0) process.exit(1);
+}
+
+function safeFix(check) {
+  try {
+    return check.fix();
+  } catch {
+    return "(fix hint unavailable)";
+  }
+}
+
 // Doctor answers "is the install healthy?". It never answered "is the
 // install SAFE?" — a config can be perfectly healthy and still hand a
 // third party the right to run code on this machine. The scanner does

package/installer/harness-bundle.js

@@ -0,0 +1,34 @@
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+// Multi-runtime instruction bundles, generated by scripts/harness_gen.py
+// and shipped inside the npm package under harness/<target>/. The
+// adapters deploy these VERBATIM — before this module existed they wrote
+// pointers at ~/.arkaos/config/<runtime>-instructions.md, a file nothing
+// ever created (issue found during the harness-generator work).
+const PKG_ROOT = join(dirname(fileURLToPath(import.meta.url)), "..");
+
+export function bundleDir(target) {
+  return join(PKG_ROOT, "harness", target);
+}
+
+// Content of one bundle file, or null when the bundle is absent (a
+// source tree without a generated harness/ — callers must fall back
+// loudly, never write a pointer to a file that does not exist).
+export function readBundleFile(target, rel) {
+  const path = join(bundleDir(target), rel);
+  return existsSync(path) ? readFileSync(path, "utf-8") : null;
+}
+
+// Flat file listing of a bundle subdirectory (e.g. cursor "rules").
+export function listBundleFiles(target, subdir = "") {
+  const base = join(bundleDir(target), subdir);
+  try {
+    return readdirSync(base).filter((name) =>
+      existsSync(join(base, name)) && !name.startsWith(".")
+    );
+  } catch {
+    return [];
+  }
+}

package/knowledge/agents-registry-v2.json

@@ -1,7 +1,7 @@
 {
   "_meta": {
     "version": "2.0.0",
-    "generated": "2026-07-14T23:46:28.709940",
+    "generated": "2026-07-20T21:08:57.022558",
     "total_agents": 86,
     "generator": "core/agents/registry_gen.py",
     "tiers": {
@@ -251,7 +251,7 @@
     {
       "id": "shadcn-padronizer-leo",
       "name": "Leo",
-      "role": "Component Library Padronizer",
+      "role": "Component Library Standardizer",
       "department": "brand",
       "tier": 2,
       "model": "sonnet",

package/knowledge/skills-manifest.json

@@ -1,7 +1,7 @@
 {
   "_meta": {
     "generator": "scripts/marketplace_gen.py",
-    "version": "4.23.0",
+    "version": "4.25.0",
     "marketplace": "arkaos"
   },
   "structural": {
@@ -420,6 +420,19 @@
         "origin": "arkaos"
       }
     },
+    "build-fix": {
+      "depts": [
+        "dev"
+      ],
+      "curated": false,
+      "plugins": [
+        "arkaos-dev@arkaos"
+      ],
+      "collision": false,
+      "provenance": {
+        "origin": "arkaos"
+      }
+    },
     "business-model": {
       "depts": [
         "community"
@@ -1095,6 +1108,19 @@
         "origin": "arkaos"
       }
     },
+    "epic-coordination": {
+      "depts": [
+        "pm"
+      ],
+      "curated": false,
+      "plugins": [
+        "arkaos-pm@arkaos"
+      ],
+      "collision": false,
+      "provenance": {
+        "origin": "arkaos"
+      }
+    },
     "estimate-forecast": {
       "depts": [
         "pm"
@@ -1108,6 +1134,19 @@
         "origin": "arkaos"
       }
     },
+    "evaluator-build-loop": {
+      "depts": [
+        "dev"
+      ],
+      "curated": false,
+      "plugins": [
+        "arkaos-dev@arkaos"
+      ],
+      "collision": false,
+      "provenance": {
+        "origin": "arkaos"
+      }
+    },
     "events-plan": {
       "depts": [
         "community"
@@ -1373,6 +1412,19 @@
         "origin": "arkaos"
       }
     },
+    "hookify": {
+      "depts": [
+        "ops"
+      ],
+      "curated": false,
+      "plugins": [
+        "arkaos-ops@arkaos"
+      ],
+      "collision": false,
+      "provenance": {
+        "origin": "arkaos"
+      }
+    },
     "identity-system": {
       "depts": [
         "brand"
@@ -2377,6 +2429,19 @@
         "origin": "arkaos"
       }
     },
+    "react-review": {
+      "depts": [
+        "dev"
+      ],
+      "curated": false,
+      "plugins": [
+        "arkaos-dev@arkaos"
+      ],
+      "collision": false,
+      "provenance": {
+        "origin": "arkaos"
+      }
+    },
     "red-team": {
       "depts": [
         "dev"
@@ -2816,6 +2881,19 @@
         "origin": "arkaos"
       }
     },
+    "spec-miner": {
+      "depts": [
+        "dev"
+      ],
+      "curated": false,
+      "plugins": [
+        "arkaos-dev@arkaos"
+      ],
+      "collision": false,
+      "provenance": {
+        "origin": "arkaos"
+      }
+    },
     "spin-sell": {
       "depts": [
         "sales"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arkaos",
-  "version": "4.23.0",
+  "version": "4.25.0",
   "description": "The Operating System for AI Agent Teams",
   "type": "module",
   "bin": {
@@ -43,6 +43,7 @@
     "installer/",
     "core/",
     "departments/",
+    "harness/",
     "mcps/",
     "scripts/",
     "config/",

package/pyproject.toml

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