arkaos 4.43.0 → 4.45.0

package/installer/doctor.js

@@ -14,6 +14,7 @@ import {
   resolveServicesForProfile,
 } from "./services.js";
 import { menubarHealthy } from "./menubar.js";
+import { LEGACY_PERSONAS } from "./adapters/claude-code.js";
 
 const INSTALL_DIR = join(homedir(), ".arkaos");
 
@@ -36,9 +37,21 @@ export function currentInstallProfile(
 
 /** Null when the check applies; otherwise the human-readable skip reason. */
 export function checkSkipReason(check, activeProfile) {
-  if (!check.minProfile) return null;
-  if (profileIncludes(activeProfile, check.minProfile)) return null;
-  return `not in ${activeProfile} profile`;
+  if (check.minProfile && !profileIncludes(activeProfile, check.minProfile)) {
+    return `not in ${activeProfile} profile`;
+  }
+  // PR-B5: per-check applicability — a project-scoped check run outside
+  // a project is an informational skip (same rendering as the profile
+  // gate), never a misleading fail. A predicate that throws must not
+  // hide its check, so the error path runs the check normally.
+  if (typeof check.skipIf === "function") {
+    try {
+      return check.skipIf() || null;
+    } catch {
+      return null;
+    }
+  }
+  return null;
 }
 
 // Resolve a single command via the platform-native locator. Returns true
@@ -206,6 +219,77 @@ export function watchMediaTooling() {
   return missing;
 }
 
+// PR-B5 (N5): a project is "repaired" when the three Quality Gate
+// reviewers are deployed WITH the QGVerdict contract and no v1 persona
+// remains dispatchable — at project scope OR at user scope, where the
+// installer used to write them as arka-<name>.md (QG r1 B2: the arka-
+// prefix defeats basename matching, so user-level detection reads the
+// frontmatter name instead). Injectable for tests; the check uses the
+// cwd and the real user agents dir.
+export function qgAgentsRepaired(
+  agentsDir = join(process.cwd(), ".claude", "agents"),
+  userAgentsDir = join(homedir(), ".claude", "agents")
+) {
+  for (const reviewer of ["marta-cqo", "eduardo-copy", "francisca-tech"]) {
+    try {
+      const text = readFileSync(join(agentsDir, `${reviewer}.md`), "utf-8");
+      if (!text.includes("QGVerdict")) return false;
+    } catch {
+      return false;
+    }
+  }
+  try {
+    for (const file of readdirSync(agentsDir)) {
+      if (!file.endsWith(".md")) continue;
+      if (LEGACY_PERSONAS.has(file.slice(0, -3))) return false;
+    }
+  } catch {
+    return false;
+  }
+  try {
+    for (const file of readdirSync(userAgentsDir)) {
+      if (!file.endsWith(".md")) continue;
+      if (isLegacyQgPersonaFile(join(userAgentsDir, file))) return false;
+    }
+  } catch {
+    // No user-level agents dir — nothing legacy can be dispatched there.
+  }
+  return true;
+}
+
+// The v1 QG trio at user scope: dispatchability follows the frontmatter
+// `name:`, not the filename. Detection only — retirement of user-level
+// files belongs to the deployer that wrote them (skill-deploy.js).
+export function isLegacyQgPersonaFile(path) {
+  try {
+    // First 500 chars only: enough for installer-written files, whose
+    // frontmatter opens the file deterministically (skill-deploy copies
+    // departments/*/agents/*.md verbatim). A hand-crafted file with the
+    // name buried deeper is out of detection scope on purpose — this
+    // check hunts the installer's own deploys, not user files.
+    const head = readFileSync(path, "utf-8").slice(0, 500);
+    const match = head.match(/^name:\s*([A-Za-z0-9-]+)\s*$/m);
+    return (
+      !!match &&
+      ["cqo", "copy-director", "tech-ux-director"].includes(match[1])
+    );
+  } catch {
+    return false;
+  }
+}
+
+// PR-B5: the hook-boundary channel has captured at least one session's
+// verdicts on this machine. Injectable for tests.
+export function qgLedgerPopulated(
+  root = join(INSTALL_DIR, "quality-gate")
+) {
+  try {
+    return readdirSync(root).length > 0;
+  } catch {
+    return false;
+  }
+}
+
 export const checks = [
   {
     name: "install-dir",
@@ -412,6 +496,40 @@ export const checks = [
     fix: () =>
       "Remove the ARKAOS_ROOT export from your shell rc (~/.zshrc) — the hooks resolve the root themselves",
   },
+  {
+    name: "qg-agents",
+    description: "Quality Gate reviewers deployed (QGVerdict contract, project + user scope)",
+    severity: "fail",
+    // PR-B5 (N5): a project whose .claude/agents/ lacks the three
+    // reviewers with the QGVerdict contract — or still carries
+    // dispatchable v1 personas — runs every Quality Gate through a
+    // contract-less agent: the dead-relay shape the campaign repaired.
+    // Project-scoped: skipped outside a project directory.
+    skipIf: () =>
+      existsSync(join(process.cwd(), ".claude", "agents"))
+        ? null
+        : "no .claude/agents here — run inside a project",
+    check: () => qgAgentsRepaired(),
+    // The two arms need two different commands: init reaches only the
+    // project scope (installer/init.js -> deployProjectAgents), while
+    // the user-scope retirement runs in deploySkills, reached from
+    // install and update — a fix string naming init alone sends the
+    // user in a dead-end loop (QG r2, both reviewers independently).
+    fix: () =>
+      "Run: npx arkaos update  (retires v1 QG personas from ~/.claude/agents/), then npx arkaos init in the project (deploys the QGVerdict reviewers into .claude/agents/)",
+  },
+  {
+    name: "qg-ledger",
+    description: "Quality Gate reviewer ledger has captured verdicts",
+    severity: "warn",
+    // PR-B5: an empty ledger root means the hook-boundary channel has
+    // never captured a verdict on this machine — the relay may still be
+    // dead in practice even with every contract deployed. Warn, not
+    // fail: a fresh install legitimately starts empty.
+    check: () => qgLedgerPopulated(),
+    fix: () =>
+      "Run a Quality Gate review — reviewer verdicts are hook-captured to ~/.arkaos/quality-gate/<session>/",
+  },
   {
     name: "profile",
     description: "User profile exists",

package/installer/index.js

@@ -817,6 +817,23 @@ function installHooks(installDir) {
     }
   }
 
+  // PR-B5 (N3): agent-provision.sh is a PreToolUse(Task) gate, not a
+  // lifecycle hook, and it is POSIX-only (no .ps1 port exists, and the
+  // adapter only registers it off-Windows). It lives OUTSIDE hookNames
+  // on purpose: that list's consistency tests require a .sh/.ps1 pair
+  // for every universal hook. Before this block the script was neither
+  // copied nor registered — settings-template.json declared it, but the
+  // template is not the executed path.
+  if (hookExt === ".sh") {
+    const provisionSrc = join(srcHooksDir, "agent-provision.sh");
+    if (existsSync(provisionSrc)) {
+      const provisionDest = join(hooksDir, "agent-provision.sh");
+      writeFileSync(provisionDest, readFileSync(provisionSrc, "utf-8"));
+      try { chmodSync(provisionDest, 0o755); } catch {}
+      ok("Hook: agent-provision.sh");
+    }
+  }
+
   if (copyHookLib(srcHooksDir, hooksDir)) {
     ok("Hook lib: _lib/");
   }

package/installer/skill-deploy.js

@@ -1,6 +1,6 @@
 import {
   copyFileSync, cpSync, existsSync, mkdirSync, readdirSync, readFileSync,
-  statSync, writeFileSync,
+  renameSync, statSync, writeFileSync,
 } from "node:fs";
 import { join } from "node:path";
 
@@ -64,7 +64,8 @@ function deployTopLevelSkill(skillSrcDir, arkaName, skillsBase) {
 /**
  * Deploy the full skill surface: main /arka skill (+ nested reference
  * bundle), department hubs, sub-skills, meta skills and agent personas.
- * Copy-only — never deletes anything already deployed.
+ * Copy-and-retire — never deletes anything already deployed (the v1 QG
+ * persona retirement renames into .arkaos-legacy/, it does not delete).
  *
  * Returns per-category counts so both callers can keep their own log
  * style. `version`/`repoRoot` stamp the main skill's VERSION and
@@ -145,6 +146,7 @@ export function deploySkills({
     // owner to a dispatchable source; hand-authored dept .md files win
     // (already deployed above), compiled ones fill the gaps.
     counts.agents += deployGateOwners(repoRoot, agentsBase, written);
+    retireLegacyQgPersonas(agentsBase);
   }
 
   log(counts);
@@ -205,10 +207,49 @@ function deployAgents(deptRoot, agentsBase, written = new Set()) {
   return deployed;
 }
 
+// PR-B5 (QG r1 B2): the three v1 Quality Gate personas predate the
+// QGVerdict contract. Deployed to ~/.claude/agents/ they keep a
+// contract-less cqo / copy-director / tech-ux-director dispatchable at
+// USER scope even after every project is repaired — the dead-relay
+// shape workstream B closes. The dept loop skips them, and the targets
+// this deployer itself wrote in earlier runs are retired — renamed
+// into .arkaos-legacy/, never deleted (the copy-only contract holds:
+// no delete primitive here). The real reviewers ship per project from
+// config/claude-agents/ via deployProjectAgents.
+const LEGACY_QG_PERSONA_FILES = [
+  "cqo.md", "copy-director.md", "tech-ux-director.md",
+];
+
+function retireLegacyQgPersonas(agentsBase) {
+  let retired = 0;
+  const legacyDir = join(agentsBase, ".arkaos-legacy");
+  for (const file of LEGACY_QG_PERSONA_FILES) {
+    const deployedName = `arka-${file}`;
+    const src = join(agentsBase, deployedName);
+    if (!existsSync(src)) continue;
+    try {
+      mkdirSync(legacyDir, { recursive: true });
+      let dest = join(legacyDir, deployedName);
+      for (let n = 1; existsSync(dest); n++) {
+        dest = join(legacyDir, `arka-${file.slice(0, -3)}-${n}.md`);
+      }
+      renameSync(src, dest);
+      // Full resolved destination: this retirement moves files in the
+      // user's HOME — the scope a reader is least able to guess.
+      console.log(`         Retired v1 QG persona: ${deployedName} -> ${dest}`);
+      retired++;
+    } catch {
+      // Best-effort — an unmovable persona stays in place, never deleted.
+    }
+  }
+  return retired;
+}
+
 function deployDeptAgents(agentsSrc, agentsBase, written) {
   let deployed = 0;
   for (const file of readdirSync(agentsSrc)) {
     if (!file.endsWith(".md")) continue;
+    if (LEGACY_QG_PERSONA_FILES.includes(file)) continue;
     const srcFile = join(agentsSrc, file);
     try {
       if (!statSync(srcFile).isFile()) continue;

package/installer/update.js

@@ -287,6 +287,18 @@ export async function update({ skillsFlag = "" } = {}) {
       try { chmodSync(destPath, 0o755); } catch {}
     }
   }
+
+  // PR-B5 (N3): the agent-provision PreToolUse(Task) gate — POSIX-only,
+  // outside hookNames on purpose (see the same block in index.js; the
+  // consistency tests require .sh/.ps1 pairs for the universal hooks).
+  if (hookExt === ".sh") {
+    const provisionSrc = join(srcHooksDir, "agent-provision.sh");
+    if (existsSync(provisionSrc)) {
+      const provisionDest = join(destHooksDir, "agent-provision.sh");
+      writeFileSync(provisionDest, readFileSync(provisionSrc, "utf-8"));
+      try { chmodSync(provisionDest, 0o755); } catch {}
+    }
+  }
   ok("Hook scripts updated");
 
   // Shared hook libraries (config/hooks/_lib/ — the Python interpreter

package/knowledge/skills-manifest.json

@@ -1,7 +1,7 @@
 {
   "_meta": {
     "generator": "scripts/marketplace_gen.py",
-    "version": "4.43.0",
+    "version": "4.45.0",
     "marketplace": "arkaos"
   },
   "structural": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arkaos",
-  "version": "4.43.0",
+  "version": "4.45.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.43.0"
+version = "4.45.0"
 description = "Core engine for ArkaOS — The Operating System for AI Agent Teams"
 readme = "README.md"
 license = {text = "MIT"}