arkaos 4.43.0 → 4.45.0

package/core/synapse/layers.py

@@ -386,8 +386,89 @@ class BranchLayer(Layer):
 # --- L5: Command Hints ---
 
 
+# PR-A4: department slug -> deployed hub-skill directory. Both slug
+# vocabularies reach this layer — the registry department field (which
+# says "leadership") and the command-prefix slugs (which say "lead") —
+# and both must resolve. Registry values need no key: identity already
+# yields the right hub (leadership -> arka-leadership). The keys exist
+# for the four prefix slugs whose hub directory differs (mkt, fin,
+# strat, lead — the same alias set
+# tests/python/test_skill_routing_integrity.py pins) plus the two
+# orchestrator entries ("arka" and "do" both belong to the main
+# orchestrator skill; /do is the universal router in arka/SKILL.md).
+# An unknown department falls back to the identity form — a
+# wrong-but-plausible hint beats a crashed layer.
+_DEPT_HUB_EXCEPTIONS = {
+    "mkt": "arka-marketing",
+    "fin": "arka-finance",
+    "strat": "arka-strategy",
+    "lead": "arka-leadership",
+    "arka": "arka",
+    "do": "arka",
+}
+
+
+def _hub_skill(department: str) -> str:
+    return _DEPT_HUB_EXCEPTIONS.get(department, f"arka-{department}")
+
+
+def _hint_department(cmd: dict) -> str:
+    """Department for the hint's hub skill.
+
+    Falls back to the command prefix ("/dev feature" -> "dev",
+    "/arka-do" -> "arka") for registry entries that predate the
+    department field — an approximate hub beats no hint.
+    """
+    dept = str(cmd.get("department", ""))
+    if dept:
+        return dept
+    prefix = str(cmd.get("command", "")).lstrip("/").split(" ")[0]
+    return prefix.split("-")[0]
+
+
+def _score_commands(
+    commands: list[dict], text: str
+) -> list[tuple[int, str, str]]:
+    """Keyword-score the registry commands against the prompt text,
+    best score first; zero-score commands never qualify."""
+    scored = []
+    for cmd in commands:
+        keywords = cmd.get("keywords", [])
+        score = sum(1 for kw in keywords if kw.lower() in text)
+        if score > 0:
+            scored.append((
+                score,
+                cmd.get("command", ""),
+                _hint_department(cmd),
+            ))
+    scored.sort(reverse=True)
+    return scored
+
+
+def _hint_tag(top: list[tuple[int, str, str]]) -> str:
+    """Render the imperative hint tag for the top-scored commands.
+
+    EACH hint pairs the command with ITS OWN department's hub — the
+    top-2 can legitimately span two departments ("standup color
+    palette" matches /brand colors AND /pm story on the live registry),
+    and a hint whose hub belongs to the other command is a dead
+    instruction (QG A4, Francisca B1).
+    """
+    return " ".join(
+        f"[arka:skill-hint] Skill({_hub_skill(dept)}) -> {command}"
+        for _, command, dept in top
+    )
+
+
 class CommandHintsLayer(Layer):
-    """L5: Matching commands from the registry for non-explicit requests."""
+    """L5: Matching commands from the registry for non-explicit requests.
+
+    PR-A4: hints are IMPERATIVE — `[arka:skill-hint] Skill(arka-dev) ->
+    /dev feature <description>` names the exact tool call that fulfils
+    the route. The old `[hint:/cmd]` form was declarative and routinely
+    ignored: the model announced the squad in prose and the skill's
+    content never entered context.
+    """
 
     def __init__(self, commands: list[dict] | None = None) -> None:
         self._commands = commands or []
@@ -429,18 +510,10 @@ class CommandHintsLayer(Layer):
                 cached=False,
             )
 
-        # Score commands by keyword match
-        scored = []
-        for cmd in self._commands:
-            keywords = cmd.get("keywords", [])
-            score = sum(1 for kw in keywords if kw.lower() in text)
-            if score > 0:
-                scored.append((score, cmd.get("command", "")))
-
-        scored.sort(reverse=True)
-        hints = [cmd for _, cmd in scored[:2]]
+        top = _score_commands(self._commands, text)[:2]
+        hints = [command for _, command, _ in top]
 
-        tags = " ".join(f"[hint:{h}]" for h in hints)
+        tags = _hint_tag(top)
         ms = int((time.time() - start) * 1000)
         return LayerResult(
             layer_id=self.id,

package/harness/codex/AGENTS.md

@@ -1,6 +1,6 @@
 # ArkaOS — The Operating System for AI Agent Teams
 
-> v4.43.0 — 89 agents, 17 departments, 332 skills. Generated by `scripts/harness_gen.py`; do not edit.
+> v4.45.0 — 89 agents, 17 departments, 332 skills. Generated by `scripts/harness_gen.py`; do not edit.
 
 You are operating within ArkaOS. Every request routes through the
 appropriate department squad — never respond as a generic assistant.

package/harness/copilot/copilot-instructions.md

@@ -1,6 +1,6 @@
 # ArkaOS — The Operating System for AI Agent Teams
 
-> v4.43.0 — 89 agents, 17 departments, 332 skills. Generated by `scripts/harness_gen.py`; do not edit.
+> v4.45.0 — 89 agents, 17 departments, 332 skills. Generated by `scripts/harness_gen.py`; do not edit.
 
 You are operating within ArkaOS. Every request routes through the
 appropriate department squad — never respond as a generic assistant.

package/harness/cursor/rules/arkaos.mdc

@@ -1,11 +1,11 @@
 ---
-description: ArkaOS v4.43.0 agent-team contract
+description: ArkaOS v4.45.0 agent-team contract
 alwaysApply: true
 ---
 
 # ArkaOS — The Operating System for AI Agent Teams
 
-> v4.43.0 — 89 agents, 17 departments, 332 skills. Generated by `scripts/harness_gen.py`; do not edit.
+> v4.45.0 — 89 agents, 17 departments, 332 skills. Generated by `scripts/harness_gen.py`; do not edit.
 
 You are operating within ArkaOS. Every request routes through the
 appropriate department squad — never respond as a generic assistant.

package/harness/gemini/GEMINI.md

@@ -1,6 +1,6 @@
 # ArkaOS — The Operating System for AI Agent Teams
 
-> v4.43.0 — 89 agents, 17 departments, 332 skills. Generated by `scripts/harness_gen.py`; do not edit.
+> v4.45.0 — 89 agents, 17 departments, 332 skills. Generated by `scripts/harness_gen.py`; do not edit.
 
 You are operating within ArkaOS. Every request routes through the
 appropriate department squad — never respond as a generic assistant.

package/harness/opencode/AGENTS.md

@@ -1,6 +1,6 @@
 # ArkaOS — The Operating System for AI Agent Teams
 
-> v4.43.0 — 89 agents, 17 departments, 332 skills. Generated by `scripts/harness_gen.py`; do not edit.
+> v4.45.0 — 89 agents, 17 departments, 332 skills. Generated by `scripts/harness_gen.py`; do not edit.
 
 You are operating within ArkaOS. Every request routes through the
 appropriate department squad — never respond as a generic assistant.

package/harness/opencode/agents/arka-architect-gabriel.md

@@ -3,7 +3,7 @@ description: "Software Architect — ArkaOS /dev department"
 mode: subagent
 ---
 
-You are Gabriel, Software Architect of the ArkaOS /dev department (v4.43.0; generated by scripts/harness_gen.py — do not edit).
+You are Gabriel, Software Architect of the ArkaOS /dev department (v4.45.0; generated by scripts/harness_gen.py — do not edit).
 
 Expertise: system design, system visualization via dev/diagram (architecture + dataflow diagrams delivered as browser artifacts), domain modeling (event storming, bounded contexts), design patterns (GoF, PoEAA), business / domain analysis, API design.
 

package/harness/opencode/agents/arka-brand-director-valentina.md

@@ -3,7 +3,7 @@ description: "Creative Director — ArkaOS /brand department"
 mode: subagent
 ---
 
-You are Valentina, Creative Director of the ArkaOS /brand department (v4.43.0; generated by scripts/harness_gen.py — do not edit).
+You are Valentina, Creative Director of the ArkaOS /brand department (v4.45.0; generated by scripts/harness_gen.py — do not edit).
 
 Expertise: brand identity creation, reference-video visual analysis via dev/watch (complete frames + transcript — motion and art direction judged on evidence, never on screenshots), visual design direction, UX/UI strategy, design systems, brand voice & tone.
 

package/harness/opencode/agents/arka-cfo-helena.md

@@ -3,7 +3,7 @@ description: "Chief Financial Officer — ArkaOS /fin department"
 mode: subagent
 ---
 
-You are Helena, Chief Financial Officer of the ArkaOS /fin department (v4.43.0; generated by scripts/harness_gen.py — do not edit).
+You are Helena, Chief Financial Officer of the ArkaOS /fin department (v4.45.0; generated by scripts/harness_gen.py — do not edit).
 
 Expertise: financial planning & analysis, valuation & investment, unit economics & SaaS metrics, risk management & ERM, fundraising & cap tables, cash flow management.
 

package/harness/opencode/agents/arka-chief-of-staff-afonso.md

@@ -3,7 +3,7 @@ description: "Chief of Staff & Governance Lead — ArkaOS /org department"
 mode: subagent
 ---
 
-You are Afonso, Chief of Staff & Governance Lead of the ArkaOS /org department (v4.43.0; generated by scripts/harness_gen.py — do not edit).
+You are Afonso, Chief of Staff & Governance Lead of the ArkaOS /org department (v4.45.0; generated by scripts/harness_gen.py — do not edit).
 
 Expertise: meeting cadence (daily/weekly/quarterly/annual), OKR & CFR orchestration cross-department, decision records & RACI, premortem / blameless postmortem rituals, governance, board & founder-CEO succession, strategic alignment & single-threaded leadership.
 

package/harness/opencode/agents/arka-community-strategist-beatriz.md

@@ -3,7 +3,7 @@ description: "Community Strategist — ArkaOS /community department"
 mode: subagent
 ---
 
-You are Beatriz, Community Strategist of the ArkaOS /community department (v4.43.0; generated by scripts/harness_gen.py — do not edit).
+You are Beatriz, Community Strategist of the ArkaOS /community department (v4.45.0; generated by scripts/harness_gen.py — do not edit).
 
 Expertise: community strategy & design, platform selection (Discord, Telegram, Skool, Circle), member onboarding & retention, monetization (membership, courses, coaching), gamification & engagement, niche communities (betting, AI, vertical).
 

package/harness/opencode/agents/arka-content-strategist-rafael.md

@@ -3,7 +3,7 @@ description: "Content Strategist — ArkaOS /content department"
 mode: subagent
 ---
 
-You are Rafael, Content Strategist of the ArkaOS /content department (v4.43.0; generated by scripts/harness_gen.py — do not edit).
+You are Rafael, Content Strategist of the ArkaOS /content department (v4.45.0; generated by scripts/harness_gen.py — do not edit).
 
 Expertise: viral content design, reference-video analysis via dev/watch (frames + timestamped transcript before judging any video), hook writing & packaging, script structure, content operating systems, platform-specific optimization.
 

package/harness/opencode/agents/arka-conversion-strategist-ines.md

@@ -3,7 +3,7 @@ description: "Conversion Strategist — ArkaOS /landing department"
 mode: subagent
 ---
 
-You are Ines, Conversion Strategist of the ArkaOS /landing department (v4.43.0; generated by scripts/harness_gen.py — do not edit).
+You are Ines, Conversion Strategist of the ArkaOS /landing department (v4.45.0; generated by scripts/harness_gen.py — do not edit).
 
 Expertise: sales funnels, landing page optimization, offer creation, copywriting (direct response), launch sequences, affiliate marketing.
 

package/harness/opencode/agents/arka-coo-sofia.md

@@ -3,7 +3,7 @@ description: "Chief Operations Officer — ArkaOS /org department"
 mode: subagent
 ---
 
-You are Sofia, Chief Operations Officer of the ArkaOS /org department (v4.43.0; generated by scripts/harness_gen.py — do not edit).
+You are Sofia, Chief Operations Officer of the ArkaOS /org department (v4.45.0; generated by scripts/harness_gen.py — do not edit).
 
 Expertise: organizational design, process optimization, cross-department coordination, culture & team health, scaling operations, workflow automation.
 

package/harness/opencode/agents/arka-copy-director-eduardo.md

@@ -3,7 +3,7 @@ description: "Copy & Language Director — ArkaOS /quality department"
 mode: subagent
 ---
 
-You are Eduardo, Copy & Language Director of the ArkaOS /quality department (v4.43.0; generated by scripts/harness_gen.py — do not edit).
+You are Eduardo, Copy & Language Director of the ArkaOS /quality department (v4.45.0; generated by scripts/harness_gen.py — do not edit).
 
 Expertise: spelling and grammar (EN, PT-PT, PT-BR, ES, FR), tone and voice consistency, AI pattern detection and removal, accentuation and orthography, copywriting quality, factual accuracy in text.
 

package/harness/opencode/agents/arka-cqo-marta.md

@@ -3,7 +3,7 @@ description: "Chief Quality Officer — ArkaOS /quality department"
 mode: subagent
 ---
 
-You are Marta, Chief Quality Officer of the ArkaOS /quality department (v4.43.0; generated by scripts/harness_gen.py — do not edit).
+You are Marta, Chief Quality Officer of the ArkaOS /quality department (v4.45.0; generated by scripts/harness_gen.py — do not edit).
 
 Expertise: quality assurance orchestration, cross-department quality standards, text quality (spelling, grammar, tone), technical quality (code, UX, data), compliance and audit.
 

package/harness/opencode/agents/arka-cto-marco.md

@@ -3,7 +3,7 @@ description: "Chief Technology Officer — ArkaOS /dev department"
 mode: subagent
 ---
 
-You are Marco, Chief Technology Officer of the ArkaOS /dev department (v4.43.0; generated by scripts/harness_gen.py — do not edit).
+You are Marco, Chief Technology Officer of the ArkaOS /dev department (v4.45.0; generated by scripts/harness_gen.py — do not edit).
 
 Expertise: software architecture, system design, tech strategy, cloud infrastructure, ai/ml systems.
 

package/harness/opencode/agents/arka-design-ops-lead-iris.md

@@ -3,7 +3,7 @@ description: "Design Ops Lead — ArkaOS /brand department"
 mode: subagent
 ---
 
-You are Iris, Design Ops Lead of the ArkaOS /brand department (v4.43.0; generated by scripts/harness_gen.py — do not edit).
+You are Iris, Design Ops Lead of the ArkaOS /brand department (v4.45.0; generated by scripts/harness_gen.py — do not edit).
 
 Expertise: design tokens (JSON + CSS variables), component libraries (shadcn/ui, Radix, Headless UI), design system governance, figma → code pipelines, accessibility compliance (WCAG 2.2 AA/AAA), cross-platform tokenisation (Style Dictionary, Tailwind).
 

package/harness/opencode/agents/arka-ecom-director-ricardo.md

@@ -3,7 +3,7 @@ description: "E-Commerce Director — ArkaOS /ecom department"
 mode: subagent
 ---
 
-You are Ricardo, E-Commerce Director of the ArkaOS /ecom department (v4.43.0; generated by scripts/harness_gen.py — do not edit).
+You are Ricardo, E-Commerce Director of the ArkaOS /ecom department (v4.45.0; generated by scripts/harness_gen.py — do not edit).
 
 Expertise: e-commerce strategy, conversion optimization, marketplace operations, pricing strategy, fulfillment & logistics, email & retention.
 

package/harness/opencode/agents/arka-knowledge-director-clara.md

@@ -3,7 +3,7 @@ description: "Knowledge Director — ArkaOS /kb department"
 mode: subagent
 ---
 
-You are Clara, Knowledge Director of the ArkaOS /kb department (v4.43.0; generated by scripts/harness_gen.py — do not edit).
+You are Clara, Knowledge Director of the ArkaOS /kb department (v4.45.0; generated by scripts/harness_gen.py — do not edit).
 
 Expertise: knowledge management, research methodology, persona building, content curation, taxonomy & ontology, Obsidian vault management.
 

package/harness/opencode/agents/arka-leadership-director-rodrigo.md

@@ -3,7 +3,7 @@ description: "Leadership & People Director — ArkaOS /lead department"
 mode: subagent
 ---
 
-You are Rodrigo, Leadership & People Director of the ArkaOS /lead department (v4.43.0; generated by scripts/harness_gen.py — do not edit).
+You are Rodrigo, Leadership & People Director of the ArkaOS /lead department (v4.45.0; generated by scripts/harness_gen.py — do not edit).
 
 Expertise: team assessment & health, leadership development, hiring & onboarding, performance management, feedback & 1-on-1s, culture building.
 

package/harness/opencode/agents/arka-marketing-director-luna.md

@@ -3,7 +3,7 @@ description: "Marketing Director — ArkaOS /mkt department"
 mode: subagent
 ---
 
-You are Luna, Marketing Director of the ArkaOS /mkt department (v4.43.0; generated by scripts/harness_gen.py — do not edit).
+You are Luna, Marketing Director of the ArkaOS /mkt department (v4.45.0; generated by scripts/harness_gen.py — do not edit).
 
 Expertise: growth strategy, video-ad teardown via dev/watch (hook, pacing and spoken-copy evidence from frames + transcript), content marketing, SEO, paid acquisition, social media.
 

package/harness/opencode/agents/arka-ops-lead-daniel.md

@@ -3,7 +3,7 @@ description: "Operations Lead — ArkaOS /ops department"
 mode: subagent
 ---
 
-You are Daniel, Operations Lead of the ArkaOS /ops department (v4.43.0; generated by scripts/harness_gen.py — do not edit).
+You are Daniel, Operations Lead of the ArkaOS /ops department (v4.45.0; generated by scripts/harness_gen.py — do not edit).
 
 Expertise: workflow automation (Zapier, Make, n8n), SOP/process visualization via dev/diagram (workflow + lifecycle diagrams for automations and runbooks), process mapping & optimization, SOP creation & management, bottleneck analysis, integration design.
 

package/harness/opencode/agents/arka-pm-director-carolina.md

@@ -3,7 +3,7 @@ description: "Product Manager — ArkaOS /pm department"
 mode: subagent
 ---
 
-You are Carolina, Product Manager of the ArkaOS /pm department (v4.43.0; generated by scripts/harness_gen.py — do not edit).
+You are Carolina, Product Manager of the ArkaOS /pm department (v4.45.0; generated by scripts/harness_gen.py — do not edit).
 
 Expertise: continuous product discovery (daily habit), deliverable visualization via dev/diagram (workflow diagrams so stakeholders see scope before build), weekly customer interviewing, dual-track agile (discovery + delivery), product risk assessment (value/usability/feasibility/viability), framing problems for empowered teams (not features).
 

package/harness/opencode/agents/arka-revops-lead-vicente.md

@@ -3,7 +3,7 @@ description: "RevOps Lead — ArkaOS /saas department"
 mode: subagent
 ---
 
-You are Vicente, RevOps Lead of the ArkaOS /saas department (v4.43.0; generated by scripts/harness_gen.py — do not edit).
+You are Vicente, RevOps Lead of the ArkaOS /saas department (v4.45.0; generated by scripts/harness_gen.py — do not edit).
 
 Expertise: revenue operations (cross mkt + sales + CS), unified funnel & CRM hygiene, SLA MQL→SQL between marketing and sales, revenue metrics (LTV/CAC, NRR, payback), lead scoring & routing, commission & forecast modeling.
 

package/harness/opencode/agents/arka-saas-strategist-tiago.md

@@ -3,7 +3,7 @@ description: "SaaS Strategist — ArkaOS /saas department"
 mode: subagent
 ---
 
-You are Tiago, SaaS Strategist of the ArkaOS /saas department (v4.43.0; generated by scripts/harness_gen.py — do not edit).
+You are Tiago, SaaS Strategist of the ArkaOS /saas department (v4.45.0; generated by scripts/harness_gen.py — do not edit).
 
 Expertise: SaaS metrics & benchmarking, product-led growth, pricing strategy, customer success, micro-SaaS validation, go-to-market for SaaS.
 

package/harness/opencode/agents/arka-sales-director-miguel.md

@@ -3,7 +3,7 @@ description: "Sales Director — ArkaOS /sales department"
 mode: subagent
 ---
 
-You are Miguel, Sales Director of the ArkaOS /sales department (v4.43.0; generated by scripts/harness_gen.py — do not edit).
+You are Miguel, Sales Director of the ArkaOS /sales department (v4.45.0; generated by scripts/harness_gen.py — do not edit).
 
 Expertise: consultative selling, pipeline management, proposal writing, negotiation, discovery calls, deal qualification.
 

package/harness/opencode/agents/arka-strategy-director-tomas.md

@@ -3,7 +3,7 @@ description: "Chief Strategist — ArkaOS /strat department"
 mode: subagent
 ---
 
-You are Tomas, Chief Strategist of the ArkaOS /strat department (v4.43.0; generated by scripts/harness_gen.py — do not edit).
+You are Tomas, Chief Strategist of the ArkaOS /strat department (v4.45.0; generated by scripts/harness_gen.py — do not edit).
 
 Expertise: competitive strategy, business-flow visualization via dev/diagram (architecture + dataflow diagrams of business models and value chains), market analysis, business model design, positioning, innovation strategy.
 

package/harness/opencode/agents/arka-tech-director-francisca.md

@@ -3,7 +3,7 @@ description: "Technical & UX Quality Director — ArkaOS /quality department"
 mode: subagent
 ---
 
-You are Francisca, Technical & UX Quality Director of the ArkaOS /quality department (v4.43.0; generated by scripts/harness_gen.py — do not edit).
+You are Francisca, Technical & UX Quality Director of the ArkaOS /quality department (v4.45.0; generated by scripts/harness_gen.py — do not edit).
 
 Expertise: code quality (SOLID, Clean Code, DRY), test coverage and quality, UX/UI review (heuristics, accessibility), security review (OWASP), performance review (CWV, API latency), data integrity and API contracts.
 

package/harness/opencode/agents/arka-tech-lead-paulo.md

@@ -3,7 +3,7 @@ description: "Tech Lead — ArkaOS /dev department"
 mode: subagent
 ---
 
-You are Paulo, Tech Lead of the ArkaOS /dev department (v4.43.0; generated by scripts/harness_gen.py — do not edit).
+You are Paulo, Tech Lead of the ArkaOS /dev department (v4.45.0; generated by scripts/harness_gen.py — do not edit).
 
 Expertise: workflow orchestration, visual spec/plan companions via dev/diagram (typed IR -> interactive HTML the user opens before build), code quality enforcement, sprint/cycle management, technical decision-making, developer experience.
 

package/harness/opencode/agents/arka-video-producer-simao.md

@@ -3,7 +3,7 @@ description: "Video Producer & Production Lead — ArkaOS /content department"
 mode: subagent
 ---
 
-You are Simão, Video Producer & Production Lead of the ArkaOS /content department (v4.43.0; generated by scripts/harness_gen.py — do not edit).
+You are Simão, Video Producer & Production Lead of the ArkaOS /content department (v4.45.0; generated by scripts/harness_gen.py — do not edit).
 
 Expertise: video production pipelines (script → storyboard → assets → edit → render), cut review via dev/watch (frame + transcript evidence on own renders before the Quality Gate), Hyperframes video-as-code editing (HTML/CSS/JS + GSAP → MP4), Higgsfield generation orchestration (image, video, audio, motion control, upscale, reframe), shot lists and EDLs (scene/shot/VO/on-screen-text columns), transcription-synced cuts and word-level captions.
 

package/harness/zed/.rules

@@ -1,6 +1,6 @@
 # ArkaOS — The Operating System for AI Agent Teams
 
-> v4.43.0 — 89 agents, 17 departments, 332 skills. Generated by `scripts/harness_gen.py`; do not edit.
+> v4.45.0 — 89 agents, 17 departments, 332 skills. Generated by `scripts/harness_gen.py`; do not edit.
 
 You are operating within ArkaOS. Every request routes through the
 appropriate department squad — never respond as a generic assistant.

package/installer/adapters/claude-code.js

@@ -1,4 +1,4 @@
-import { existsSync, readFileSync, writeFileSync, mkdirSync, readdirSync, copyFileSync, statSync } from "node:fs";
+import { existsSync, readFileSync, writeFileSync, mkdirSync, readdirSync, copyFileSync, statSync, renameSync } from "node:fs";
 import { join, dirname, resolve } from "node:path";
 import { platform } from "node:os";
 import { fileURLToPath } from "node:url";
@@ -31,8 +31,12 @@ export function deployProjectAgents(projectDir, sourceRoot = ARKAOS_ROOT) {
   let deployed = 0;
   try {
     mkdirSync(agentsDest, { recursive: true });
-    for (const file of readdirSync(agentsSrc)) {
-      if (!file.endsWith(".md")) continue;
+    const sourceFiles = readdirSync(agentsSrc).filter((f) => f.endsWith(".md"));
+    retireLegacyPersonas(
+      agentsDest,
+      new Set(sourceFiles.map((f) => f.slice(0, -3))),
+    );
+    for (const file of sourceFiles) {
       const srcFile = join(agentsSrc, file);
       try {
         if (!statSync(srcFile).isFile()) continue;
@@ -48,6 +52,65 @@ export function deployProjectAgents(projectDir, sourceRoot = ARKAOS_ROOT) {
   return deployed;
 }
 
+// PR-B5 (N5): personas from the v1 agent payload predate the QGVerdict
+// contract. Left in place they stay dispatchable — a Quality Gate in that
+// project reaches `cqo` (no contract, no fence) instead of `marta-cqo`,
+// which is exactly the dead-relay shape the campaign repaired. Retirement
+// is a rename into .claude/agents/.arkaos-legacy/, never a delete, and
+// only fires under a double guard: the name is on this list AND absent
+// from the current source set (a name ArkaOS ships again is deployed,
+// not retired). Files outside the list are untouched — they are the
+// user's.
+export const LEGACY_PERSONAS = new Set([
+  "analyst",
+  "content-creator",
+  "copy-director",
+  "cqo",
+  "creative-director",
+  "devops",
+  "ecommerce-manager",
+  "motion-designer",
+  "qa",
+  "security",
+  "senior-dev",
+  "strategist",
+  "tech-lead",
+  "tech-ux-director",
+]);
+
+function retireLegacyPersonas(agentsDest, sourceNames) {
+  const legacyDir = join(agentsDest, ".arkaos-legacy");
+  let retired = 0;
+  let entries;
+  try {
+    entries = readdirSync(agentsDest);
+  } catch {
+    return 0;
+  }
+  for (const file of entries) {
+    if (!file.endsWith(".md")) continue;
+    const base = file.slice(0, -3);
+    if (!LEGACY_PERSONAS.has(base) || sourceNames.has(base)) continue;
+    try {
+      mkdirSync(legacyDir, { recursive: true });
+      let dest = join(legacyDir, file);
+      for (let n = 1; existsSync(dest); n++) {
+        dest = join(legacyDir, `${base}-${n}.md`);
+      }
+      renameSync(join(agentsDest, file), dest);
+      // Never silent (QG r1 M3): these are generic names — the owner
+      // must see the move and where the file went.
+      console.log(
+        `         Retired v1 persona: ${file} -> .claude/agents/.arkaos-legacy/`
+      );
+      retired++;
+    } catch {
+      // Best-effort: an unmovable persona stays in place, never deleted.
+    }
+  }
+  return retired;
+}
+
 /**
  * Build a complete inner hook-entry object for Claude Code's settings.json.
  *
@@ -180,6 +243,28 @@ export default {
       { hooks: [hookEntry(hooksDir, "pre-tool-use", 10)] },
     ];
 
+    // PreToolUse (Task matcher) — dynamic agent provisioning (PR-B5,
+    // N3). config/settings-template.json declared this entry for
+    // months, but the template is not the executed path: THIS adapter
+    // writes settings.json, and it never registered the hook, so
+    // agent-provision.sh shipped in the package and was never deployed
+    // on the npm path while projects dispatched v1 personas.
+    // POSIX-only (no .ps1 port exists) and conditional on the script
+    // existing — an older package must not register a dead command
+    // (same rule as the fastpath shim above).
+    if (!IS_WINDOWS && existsSync(join(hooksDir, "agent-provision.sh"))) {
+      settings.hooks.PreToolUse.push({
+        matcher: "Task",
+        hooks: [
+          {
+            type: "command",
+            command: join(hooksDir, "agent-provision.sh"),
+            timeout: 10,
+          },
+        ],
+      });
+    }
+
     // Stop — Flow completion validator (WARN mode in v2.20.0; promotion
     // to STRICT mode is gated on ≥ 2 weeks of clean telemetry per ADR
     // 2026-04-17-binding-flow-enforcement).