@agentikos/omega-os 0.2.0 → 0.19.6

package/omega/Agentik_SSOT/docs/LAYERS.md

@@ -0,0 +1,90 @@
+# OmegaOS Layered Architecture
+
+> Five layers. Each independently usable. All five share ONE credential:
+> the Claude Code Max OAuth token at `~/.claude/.credentials.json`.
+
+```
+┌──────────────────────────────────────────────────────────────────────┐
+│  Layer 1 ─ Human                                                     │
+│  Telegram / CLI / web — operator intent in natural language          │
+└────────────────────────────────────────┬─────────────────────────────┘
+                                         │
+┌────────────────────────────────────────▼─────────────────────────────┐
+│  Layer 2 ─ Hermes (Nous Research, opt-in)                            │
+│  Autonomous self-improving agent. Cross-platform gateway, scheduled  │
+│  automations, skill creation from experience, dialectic user model.  │
+│  Uses CLAUDE_CODE_OAUTH_TOKEN from ~/.claude/.credentials.json.       │
+│  Bridge: `omega hermes {install,link,status,ask}`                    │
+└────────────────────────────────────────┬─────────────────────────────┘
+                                         │
+┌────────────────────────────────────────▼─────────────────────────────┐
+│  Layer 3 ─ AISB (Agentik Intake Service Bus)                         │
+│  Telegram-first intake. Classifies the message, picks a topology,    │
+│  dispatches a mission to the Engine. Lives in $OMEGA_HOME.           │
+└────────────────────────────────────────┬─────────────────────────────┘
+                                         │
+┌────────────────────────────────────────▼─────────────────────────────┐
+│  Layer 4 ─ Oracle (the planner)                                      │
+│  Reads the mission, plans 1..N worker subtasks, each with a          │
+│  verify_cmd + file ownership. Persistent tmux session.               │
+└────────────────────────────────────────┬─────────────────────────────┘
+                                         │
+┌────────────────────────────────────────▼─────────────────────────────┐
+│  Layer 5 ─ Workers (executors)                                       │
+│  One per subtask. Persistent tmux session. Runs `claude -p` with     │
+│  the worker envelope + injected skill palette. Writes .done.json     │
+│  on completion. Verified by the audit gate before the parent's      │
+│  barrier resolves.                                                   │
+└──────────────────────────────────────────────────────────────────────┘
+```
+
+## Why this shape
+
+| Layer | Role | Runtime | Credential |
+|---|---|---|---|
+| 1 | Intent | Human | n/a |
+| 2 | Autonomous companion | Hermes (Python, ~/.hermes) | Claude Max OAuth |
+| 3 | Mission intake | OmegaOS engine | Claude Max OAuth |
+| 4 | Planning | Persistent tmux + `claude -p` | Claude Max OAuth |
+| 5 | Execution | Persistent tmux + `claude -p` | Claude Max OAuth |
+
+Every layer below #1 calls Claude through the same OAuth credential. No
+API key burn, no separate auth surface, no extra account to manage. The
+token rotates server-side via the standard Claude Code refresh flow;
+every layer reads the live file (`~/.claude/.credentials.json`) on each
+call so refresh propagates automatically.
+
+## Layer choice cheat-sheet
+
+| You want to | Use |
+|---|---|
+| One-shot CLI question | Layer 5 directly: `claude -p "..."` |
+| Verified-completion multi-worker mission | Layer 3-5: `omega run "..."` |
+| Recurring scheduled mission (cron) | Layer 3-5: `omega cadence schedule ...` |
+| Cross-platform chat (Telegram, Discord, …) | Layer 2: `hermes gateway` |
+| Skill creation from experience over time | Layer 2: Hermes's learning loop |
+| Long-running autonomous research | Layer 2: Hermes + scheduled task |
+| Visual codebase exploration | Sidecar: `omega ua run <project>` |
+
+## Bridges
+
+* `omega hermes` — Layer 2 ↔ rest of stack. Hermes can call OmegaOS via
+  the `omega` CLI (any of layers 3-5). OmegaOS can call Hermes via
+  `omega hermes ask "..."`.
+* `omega ua` — Understand-Anything sidecar. Builds an interactive
+  knowledge graph of any project; `omega ua consume` lands the graph
+  into the Engine's GraphRetriever so Oracle/workers can answer
+  "where in the code is X?" via Graph RAG.
+* `omega ma` — Anthropic Managed Agents (opt-in, API-key-only). NOT
+  part of the OAuth stack; only used when explicitly opted into per
+  topology entry.
+
+## What this is NOT
+
+* Hermes is not a "wrapper" around OmegaOS — it has its own loop, its
+  own skills, its own memory. The bridge gives both runtimes the
+  ability to delegate to each other.
+* Layer 2 is OPTIONAL. OmegaOS without Hermes is a complete agentic
+  OS (layers 1+3-5). Adding Hermes buys you the autonomous companion
+  + cross-platform gateway + learning loop. Removing Hermes removes
+  none of OmegaOS's verified-completion guarantees.

package/omega/Agentik_SSOT/docs/USER-JOURNEY.md

@@ -0,0 +1,283 @@
+# OmegaOS — User Journey (install → daily use)
+
+> What happens, in order, from `npx @agentikos/omega-os` to a 24/7
+> autonomous agent on Telegram that you watch via tmux prefix+Z.
+
+## Layer cheat-sheet (one credential for all five)
+
+```
+L1  Human                    Telegram, CLI, web, Hermes Desktop
+L2  Hermès        (opt-in)   Autonomous companion, learning loop, gateway
+L3  AISB                     Intake bus, classifies, dispatches
+L4  Oracle                   Plans the mission, picks topology
+L5  Workers                  Persistent-tmux executors with verified completion
+```
+
+All five share **one** OAuth: `~/.claude/.credentials.json`. No API key
+burn, no separate auth surface.
+
+---
+
+## Phase A — Install (2-3 minutes)
+
+```bash
+npx -y @agentikos/omega-os
+# or
+curl -fsSL https://raw.githubusercontent.com/agentik-os/OmegaOS/main/install.sh | bash
+```
+
+The installer renders:
+
+1. **ASCII banner + version**
+2. **Pre-flight detection card** — OS, RAM, disk, internet, ✓/✗ per
+   required (git, python3, tmux, sqlite3, curl, jq) and optional
+   (claude, uv, node, age, gh) tools.
+3. **Profile picker** (whiptail) when run interactively: vps /
+   workstation / minimal.
+4. **17 steps with `[N/M]` progress + per-step elapsed time**:
+   preflight, system deps, LLM CLIs, structure, AISB suite, audit
+   skills, engine venv, Claude Code settings, accounts, providers, MCP
+   picker, Claude plugins, Telegram, autonomous, RAG, first project,
+   services (systemd / launchd), doctor.
+5. **PATH auto-setup** in `~/.zshrc` / `~/.bashrc` (idempotent marker
+   block, opt-out `--no-path-setup`).
+6. **Post-install card** — boxed verdict (`READY` / `PARTIAL` /
+   `NOT READY`), home path, total elapsed, 5 numbered next-step
+   commands.
+
+At secrets-required steps, the installer prompts (and chmod-600 +
+age-encrypts via `Agentik_Vault/`):
+
+* Claude OAuth (`claude login` opens a browser → token saved at
+  `~/.claude/.credentials.json`)
+* MCP secrets (`GITHUB_TOKEN`, `NOTION_API_KEY`, …)
+* Telegram bot token + group id
+
+---
+
+## Phase B — Wire Hermès (Layer 2) — opt-in but recommended
+
+```bash
+omega hermes install         # ~1 min; runs upstream install.sh
+omega hermes link            # bind to live Claude OAuth (live read; never persists)
+omega hermes brief write     # teach Hermès the L1-L5 architecture + how to dispatch
+```
+
+That third command is the **auto-improvement seed**. It writes a
+`SKILL.md` inside `~/.hermes/skills/omega/` that Hermès reads on every
+start. The brief tells it:
+
+* It is Layer 2 — chat + memory + cross-platform gateway
+* L3-L5 lives below — when the user asks for engineering work, delegate
+  via `omega run`, `omega genesis`, `omega plan run`
+* Read `.done.json` files after each dispatch and write learning notes
+  to its memory (Honcho dialectic user model)
+* Skill-routing map per role (what audits to suggest when)
+
+Verify:
+
+```bash
+omega hermes status
+  hermes installed:    ✓
+  hermes home:         /home/hacker/.hermes
+  omega.env linked:    ✓
+  Claude OAuth token:  ✓  (max)
+  token expires in:    7.4 h
+
+omega hermes brief status
+  ✓  brief at /home/hacker/.hermes/skills/omega/SKILL.md  (5846 bytes)
+```
+
+After each mission, the operator (or a cron) runs:
+
+```bash
+omega hermes brief observe <slug> <task_id>
+```
+
+…which appends a one-line learning event to
+`~/.hermes/memory/omega_observations.jsonl`. Hermès's memory provider
+ingests it; next dispatch is smarter.
+
+---
+
+## Phase C — Polish tmux (one command)
+
+The installer dropped a minimal tmux.conf at
+`$OMEGA_HOME/Agentik_Tools/tmux.conf`. To upgrade to the **pro config**
+(paste-fix Termius, session-kill forensics, smart scroll, OSC 52
+clipboard, prefix+Z popup):
+
+```bash
+omega tmux install --profile pro
+  ✓ ~/.tmux.conf installed (profile: pro)
+     backup → ~/.tmux.conf.bak.20260525-143000
+     bundled → /home/hacker/Omega/Agentik_Tools/tmux.conf
+
+  Reload tmux NOW:
+     prefix+r          # or `tmux source-file ~/.tmux.conf`
+```
+
+From any tmux session: **prefix+Z** opens a popup with every OmegaOS
+session, grouped by category (AISB / Oracle / Worker / Dev / Linear /
+Home / Other). Pick → switch-client cleanly without leaving tmux.
+
+```bash
+omega tmux list        # all sessions, grouped
+omega tmux health      # population summary + stale workers
+omega tmux menu        # the popup body (same as prefix+Z)
+```
+
+Every Claude Code / Hermès / Cowork / LLM CLI session you spawn via
+`omega worker spawn`, `omega aisb chat`, etc. lands in its own tmux
+session. The pro config logs every `session-closed` + `pane-died` to
+`$OMEGA_HOME/Agentik_Extra/var/logs/tmux-session-kills.log` — a
+mystery dead worker leaves a trace.
+
+---
+
+## Phase D — Daily use
+
+### From Telegram (the most common path)
+
+You type a message in the Telegram topic bound to your project:
+
+```
+fix the typo in apps/web/app/page.tsx
+```
+
+What happens, in order:
+
+1. **AISB (L3)** receives the message, classifies the intent
+   (`bug-fix`), picks the topology.
+2. **Oracle (L4)** is spawned in a fresh tmux session
+   (`myproj-oracle-N`), plans 1 worker.
+3. **Worker (L5)** is spawned in `myproj-worker-1-fix-typo`. Runs
+   `claude -p` with the worker envelope + injected skill palette
+   (`/codeaudit`, `/pursue`, etc).
+4. Worker writes `.done.json` (status=done_clean, files_changed,
+   usage, cost).
+5. **Audit gate** runs the `verify_cmd` from the brief. Refuses to
+   flip the task to VERIFIED if it fails.
+6. **PDF report** generated + Telegram message: `✓ done in 47s — see report.pdf`.
+
+You watch all of this via prefix+Z if you SSH in. Otherwise you just
+wait for Telegram.
+
+### From the VPS (SSH)
+
+```bash
+ssh -p 42820 hacker@<vps-domain>
+omega                         # interactive whiptail menu
+omega status                  # every task + derived state
+omega run "..."               # quick one-shot
+omega genesis new my-app --intent "..."      # new project pipeline
+omega plan build my-app && omega plan run my-app   # multi-day autonomous loop
+omega tmux                    # tmux session picker
+prefix+Z                      # tmux popup with omega tmux menu inside
+```
+
+### From Hermes Desktop (laptop UI on remote VPS)
+
+```bash
+# On the VPS:
+omega hermes-desktop install
+# → prints a profile to paste into Hermes Desktop:
+#   Name:    OmegaOS VPS
+#   URL:     http://127.0.0.1:8642
+#   API key: <40 hex chars>
+
+# Then either bind public (with reverse proxy + TLS), or tunnel:
+ssh -L 8642:127.0.0.1:8642 -p 42820 hacker@<vps-domain>
+
+# In one tmux session on the VPS:
+omega hermes-desktop serve --port 8642
+```
+
+On the laptop:
+
+1. Install Hermes Desktop from https://hermesagents.cc/.
+2. Settings → Profiles → New → paste the URL + API key.
+3. Switch to that profile.
+
+Now every chat message in Hermes Desktop hits the VPS, gets answered
+by Hermès (running on the VPS, sharing the Claude OAuth), and
+engineering work delegates down to AISB → Oracle → Workers as usual.
+
+---
+
+## Phase E — Mises à jour silencieuses
+
+Every `omega …` invocation does a cached check (24h) for a newer
+`@agentikos/omega-os`. If one exists, a single stderr line:
+
+```
+[omega] update available: 0.18.1 → 0.19.0  run `omega update apply` to install
+```
+
+To opt-in to nightly auto-apply (backup → npm install → migrations →
+verify → rollback on fail):
+
+```bash
+omega update auto enable
+```
+
+A charter lands at `Agentik_Orchestration/autonomous/auto-update.yaml`
+that fires at 04:00 UTC via the autonomous supervisor.
+
+---
+
+## Phase F — Handoff between sessions
+
+When you `/clear` mid-work, you write a handoff first:
+
+```
+/handoff
+```
+
+…which writes the 5-section memo to your project's `HANDOFF.md`. The
+next agent in the same project reads it on first turn:
+
+```bash
+omega handoff read --project my-app
+```
+
+Five sections, non-negotiable: Mission · State · Files touched · Dead
+ends · Next.
+
+---
+
+## Quick reference — everything you can run
+
+| Action | Command |
+|---|---|
+| Status of everything | `omega doctor` |
+| Interactive menu | `omega` |
+| Quick mission | `omega run "..."` |
+| New project (vision → plan) | `omega genesis new <slug> --intent "..."` |
+| Run plan (multi-day) | `omega plan run <slug>` |
+| Forensic audit | `omega audit run codeaudit` (17 available) |
+| Tmux session picker | `prefix+Z` (or `omega tmux menu`) |
+| Stale-session cleanup | `omega cleanup --deep` |
+| Cross-source memory search | `omega memory search "..."` |
+| Hermès one-shot | `omega hermes ask "..."` |
+| Update OmegaOS | `omega update apply` |
+| Handoff between sessions | `/handoff` (Claude Code) or `omega handoff write` |
+| Hermes Desktop remote | `omega hermes-desktop install` |
+
+---
+
+## Auto-improvement — how the system gets better
+
+Three loops run in parallel:
+
+1. **Per-mission**: every `.done.json` → `omega learn reflect` writes
+   an Insight to `Agentik_Extra/staging/promotion/` for triage.
+2. **Hermès dialectic**: `omega hermes brief observe` appends to
+   Hermès's memory log; Honcho updates the user model.
+3. **Quality Arsenal trend**: `omega audit history` reveals score
+   trends per project; recurring weak audits trigger Smith reflection
+   proposals.
+
+Every loop reads OmegaOS's event log (`Agentik_Runtime/eventlog/omega.db`)
+as ground truth. The system gets smarter by observing its own outcomes,
+not by being prompted to "be smarter".

package/omega/Agentik_SSOT/docs/quality-arsenal/ARSENAL-INTERCONNECTIONS.md

@@ -0,0 +1,283 @@
+---
+name: ARSENAL-INTERCONNECTIONS
+description: >
+  Complete interconnection map for the 14 Quality Arsenal audits. Defines ownership
+  boundaries (no duplicate findings), dispatch-order constraints, input/output contracts
+  between audits, shared finding types with routing rules, and parallel-dispatch groups.
+  Referenced by /aisb, /metaudit, rule 43 Linear pipeline, and Oracle orchestrators.
+  NOT a user-invokable skill — shared source of truth, like QUALITY-ARSENAL-PREAMBLE.md.
+---
+
+# Quality Arsenal — Interconnections Map v1.0
+
+> *"Each audit is a lens. Together they must focus, not interfere."*
+
+---
+
+## 1. WHAT EACH AUDIT OWNS (single-source ownership — no duplicates)
+
+| Audit | Primary question | Owns exclusively |
+|-------|-----------------|-------------------|
+| `/codeaudit` | Is the code SOLID? | SOLID violations, phantom imports, circular deps, dead code, contract drift, git safety, fix-gate smoke tests for integrations |
+| `/debugaudit` | What is BROKEN right now? | Runtime console errors, network failures mid-flow, visual regressions, chaos-mode fuzzing, authenticated-state behavior |
+| `/uiuxaudit` | Is the interface COHERENT? | Visual coherence (color/typography/spacing), Gestalt principles, design-system adherence, AI-generic smells, dark-mode parity |
+| `/flowaudit` | Does the EXPERIENCE work? | User journeys, state-machine integrity, dead ends, promise-vs-experience (runtime), error recovery paths, onboarding |
+| `/featureaudit` | Is the product COMPLETE? | PRD coverage, feature parity with competitors, inferred-vs-explicit PRD fallback, WebSearch-bounded parity research |
+| `/perfaudit` | Is it FAST enough? | Core Web Vitals measurement, bundle size, render timing, memory profiling, perf regressions vs baseline |
+| `/secaudit` | Is it SECURE? | OWASP Top 10 exploitation, XSS/SQLi/SSRF/IDOR probes, auth bypass, privilege escalation, rate-limit-safe fuzzing |
+| `/a11yaudit` | Is it ACCESSIBLE? | WCAG 2.1 AA, keyboard nav, ARIA, screen-reader automation, RTL/i18n layout, reduced-motion |
+| `/seoaudit` | Is it DISCOVERABLE? | Crawlability, indexability, meta tags, Schema.org markup, GEO (AI-search optimization), content decay |
+| `/copyaudit` | Is the COPY clear? | Word-level tone, claim clarity (static), CTA text, jargon, banned-phrase scan, i18n wrapping |
+| `/dxaudit` | Is the DX smooth? | README quality (20-item rubric), setup time (external runner), error messages, dev-loop UX |
+| `/motionaudit` | Is motion PURPOSEFUL? | CSS/JS/WebGL/P5/Lottie/video/GIF animation audit, purpose classification, reduced-motion compliance |
+| `/dataaudit` | Is the DATA intact? | Schema validation, migration safety (DB backup gate), orphan records, referential integrity, data sampling |
+| `/apiaudit` | Is the API solid? | REST/GraphQL contract compliance, auth middleware presence, rate-limit specs, inference-mode labeling |
+
+**Rule:** A given finding has exactly ONE owner. If two audits disagree, the ownership table wins.
+
+---
+
+## 2. OWNERSHIP CONFLICTS & RESOLUTIONS
+
+Cases where the boundary was fuzzy — now formally resolved:
+
+| Concern | Conflict | Resolution |
+|---------|---------|------------|
+| **Core Web Vitals** | `/perfaudit` measures, `/seoaudit` cares about ranking impact | `/perfaudit` MEASURES + OWNS REMEDIATION. `/seoaudit` READS `audits/.perfaudit/verdict.json` (if <24h old) and scores only the SEO-ranking-impact dimension. No re-measurement. |
+| **Auth security** | `/apiaudit` static-checks auth middleware, `/secaudit` exploits it | `/apiaudit` owns STATIC auth correctness. `/secaudit` owns RUNTIME exploitation. Shared finding if both agree = CRITICAL elevation. |
+| **Promise vs experience** | `/flowaudit` checks runtime, `/copyaudit` checks static text | `/copyaudit` owns WORD-level (tone, jargon, 5-second test). `/flowaudit` owns LABEL-vs-ACTION at runtime. Duplicate file:line → prefer `/flowaudit` (behavior > text). |
+| **i18n wrapping** | `/a11yaudit` + `/copyaudit` both care | `/copyaudit` owns wrapping detection (hardcoded string regex). `/a11yaudit` owns rendered-locale verification (RTL, pluralization). |
+| **Dead ends** | `/flowaudit` owns, `/uiuxaudit` sometimes notices | `/flowaudit` exclusively. If `/uiuxaudit` notices a dead end, emit as a `/flowaudit`-routed finding (cross-audit hand-off). |
+| **Banned phrases** | `/copyaudit` scans copy, `/metaudit` scans commands | `/copyaudit` scans user-facing copy. `/metaudit` scans `.md` configuration files. No overlap (different target surfaces). |
+| **Error messages** | `/dxaudit` (helpful?), `/copyaudit` (clear?), `/debugaudit` (accurate?) | `/dxaudit` owns HELPFULNESS (actionable, diagnosable). `/copyaudit` owns CLARITY (plain language). `/debugaudit` owns ACCURACY (matches actual error). Rare 3-way overlap = same underlying error string — elevate to CRITICAL. |
+| **Non-UI contexts** | Who audits a CLI? | `/codeaudit`, `/dxaudit` (primary), `/copyaudit` (help text), `/secaudit`, `/perfaudit`, `/dataaudit`, `/apiaudit`. ABORT list: `/uiuxaudit`, `/flowaudit`, `/motionaudit`, `/seoaudit`. |
+
+---
+
+## 3. DISPATCH ORDER CONSTRAINTS
+
+Some audits depend on others' outputs. Dispatch order matters when running them together.
+
+### Strict ordering (dependent audits)
+
+```
+/perfaudit   →  /seoaudit         (/seoaudit reads audits/.perfaudit/verdict.json for CWV scoring)
+/apiaudit    →  /secaudit         (/secaudit exploits the contract /apiaudit documented)
+/codeaudit   →  /debugaudit       (fix code phantoms before looking for runtime bugs)
+/dataaudit   →  /apiaudit         (schema defines API response shape)
+/codeaudit   →  /dataaudit        (model types define schema)
+```
+
+### Independent (can run in parallel)
+
+Any audit not in the strict chain above can run in parallel with others, subject to concurrency locks (preamble §3) and distinct `.{audit}/` output directories.
+
+### The Rule-43 Quadruple (Linear ticket pipeline)
+
+For Linear ticket resolution (per `~/.claude/docs/rules-archive/43-linear-ticket-pipeline.md` Step 8):
+
+```
+Parallel dispatch (same ticket, same files_modified, same page_url):
+  /codeaudit  --files={files} --ticket={T} --url={url}
+  /uiuxaudit  --files={files} --ticket={T} --url={url}
+  /flowaudit  --files={files} --ticket={T} --url={url}
+  /debugaudit --files={files} --ticket={T} --url={url}
+
+Each writes to: .linear-fix/{TICKET}/{audit}.json
+Threshold: each = 100/100 (rule 43 step 8b fix-and-reaudit until 100)
+```
+
+The dynamic audit chain (4-12 audits selected by audit-selector.py) is safe to parallelize because:
+- Each writes to a ticket-specific distinct path (no output collision)
+- Each concurrency-locks its own `.{audit}/.lock` (no same-audit collision)
+- No output dependency between them (CWV deferral rule applies elsewhere)
+
+### The `/aisb full` / `/godmode` octad (broad verification)
+
+For comprehensive verification across a project, run 8 parallel audits grouped by independence:
+
+```
+Group 1 (independent): /codeaudit, /perfaudit, /secaudit, /a11yaudit
+Group 2 (depends on Group 1): /debugaudit, /seoaudit, /dataaudit, /apiaudit
+Group 3 (independent of 1+2): /uiuxaudit, /flowaudit, /featureaudit, /motionaudit, /copyaudit, /dxaudit
+```
+
+Dispatch: Group 1 → wait for /codeaudit + /perfaudit + /apiaudit + /dataaudit completion → Group 2. Group 3 runs parallel to 1+2.
+
+---
+
+## 4. INPUT / OUTPUT CONTRACTS BETWEEN AUDITS
+
+Machine-readable handoffs documented here:
+
+| Producer | Consumer | File | Contents |
+|----------|---------|------|----------|
+| `/perfaudit` | `/seoaudit` | `audits/.perfaudit/verdict.json` | `{phases: [{id: 6, name: "CWV", metrics: {lcp, fid/inp, cls, ttfb}}]}` — /seoaudit reads `metrics` and scores ranking impact |
+| `/apiaudit` | `/secaudit` | `audits/.apiaudit/verdict.json` | `{findings: [{type: "auth_check_missing", endpoint: "..."}]}` — /secaudit elevates to CRITICAL if exploit confirmed |
+| `/codeaudit` | `/debugaudit` | `audits/.codeaudit/verdict.json` | `{findings: [{type: "phantom_import", file: "..."}]}` — /debugaudit skips console-error findings already covered |
+| `/dataaudit` | `/apiaudit` | `audits/.dataaudit/verdict.json` | Schema type info — /apiaudit validates REST/GraphQL response shape matches |
+| Any audit | `/metaudit` | `.{audit}/verdict.json` | `preamble_version`, `compliance_score`, `skill_used` — /metaudit's Phase 1 compliance check |
+
+**Contract violation** (e.g., /seoaudit running without /perfaudit's output despite expecting it) → /seoaudit either runs its own CWV measurement (fallback) or emits a warning in verdict.md. Never fails silently.
+
+---
+
+## 5. SHARED FINDING TYPES & ROUTING
+
+Some finding types appear across multiple audits. Routing rules:
+
+| Finding type | Audits that detect | Routing rule |
+|-------------|-------------------|--------------|
+| **Banned phrase (rule 46)** | `/copyaudit` (user copy), `/metaudit` (command config) | `/copyaudit` owns user-facing copy. `/metaudit` owns `.md` configuration. Different targets = no dedupe. |
+| **Stale Skill() ref** | `/metaudit` (exclusively) | Only `/metaudit` scans command files. |
+| **Dead end in flow** | `/flowaudit` (exclusively) | `/uiuxaudit` notices → forward to `/flowaudit` queue. |
+| **Auth bypass** | `/apiaudit` (static), `/secaudit` (runtime) | Both can emit. Shared agreement = CRITICAL. |
+| **Regression vs baseline** | `/perfaudit` (perf), `/debugaudit` (visual), `/seoaudit` (ranking) | Each owns its own baseline file. |
+| **Integration broken post-fix** | ANY code-touching audit via Phase 23 smoke gate | First audit to detect aborts the fix + reverts. Others inherit revert state. |
+| **Broken screenshot / 4xx-5xx page** | `/debugaudit` ABORTS (preamble §5) | NEVER marked as "pass with warning" — ABORT is the only correct response. |
+
+---
+
+## 6. HANDOFF LIFECYCLE (what flows between audits during a full run)
+
+```
+                 ┌──────────────────┐
+                 │   /aisb / Oracle │
+                 └────────┬─────────┘
+                          │ dispatch
+                          ▼
+          ┌──────────────────────────────────┐
+          │  Group 1 (no deps, parallel)     │
+          │  /codeaudit  /perfaudit          │
+          │  /secaudit   /a11yaudit          │
+          │  /dataaudit  /apiaudit (partial) │
+          └───┬────────┬─────┬────────┬──────┘
+              │        │     │        │
+              ▼        ▼     ▼        ▼
+          ┌──────────────────────────────────┐
+          │  Handoff files                   │
+          │  audits/.codeaudit/verdict.json         │
+          │  audits/.perfaudit/verdict.json (CWV)   │
+          │  audits/.dataaudit/verdict.json (types) │
+          │  audits/.apiaudit/verdict.json (partial)│
+          └───┬──────────────────────────────┘
+              │ consumed by
+              ▼
+          ┌──────────────────────────────────┐
+          │  Group 2 (depends on Group 1)    │
+          │  /debugaudit (reads codeaudit)   │
+          │  /seoaudit   (reads perfaudit)   │
+          │  /apiaudit   (reads dataaudit)   │
+          │  /secaudit   (reads apiaudit)    │
+          └──────────────────────────────────┘
+
+          ┌──────────────────────────────────┐
+          │  Group 3 (fully independent,     │
+          │  runs parallel to 1+2)           │
+          │  /uiuxaudit  /flowaudit          │
+          │  /featureaudit /motionaudit      │
+          │  /copyaudit   /dxaudit           │
+          └──────────────────────────────────┘
+                          │
+                          ▼
+          ┌──────────────────────────────────┐
+          │  /metaudit (compliance check)    │
+          │  Verifies all 14 wrote verdicts  │
+          │  with preamble_version="1.0"     │
+          └──────────────────────────────────┘
+                          │
+                          ▼
+                 ┌──────────────────┐
+                 │  Final verdict   │
+                 │  to Oracle/User  │
+                 └──────────────────┘
+```
+
+---
+
+## 7. ANTI-PATTERNS (what NOT to do)
+
+1. **Never run audits sequentially when they're independent** — wastes days instead of hours.
+2. **Never dispatch a dependent audit before its producer** — `/seoaudit` before `/perfaudit` = duplicate CWV work.
+3. **Never combine audits into a single "audit" worker** — per rule 001, always invoke specific skills.
+4. **Never interpret 403/401 as a pass** — preamble §5 ABORT rule is absolute.
+5. **Never mark an audit "done" without output-gate verification** — check files exist with valid schemas.
+6. **Never run without scoped flags when rule 43 requires them** — `--url`, `--ticket`, `--files` are MANDATORY for Linear pipeline.
+7. **Never duplicate findings across audits** — ownership table (§1) wins, cross-forward if one audit notices another's turf.
+8. **Never skip `/metaudit` after touching any command `.md` file** — drift starts immediately.
+9. **Never run a `/uiuxaudit` / `/flowaudit` / `/motionaudit` / `/seoaudit` on a non-UI project** — ABORT per preamble §5.
+10. **Never run two instances of the same audit simultaneously on the same project** — concurrency lock blocks, but don't even try.
+
+---
+
+## 8. HOW /aisb AND ORACLES PICK AUDITS
+
+When a task arrives, Oracle classifies it and picks the minimal audit set:
+
+| Task signal | Audits to dispatch |
+|-------------|-------------------|
+| "fix this bug" + specific file | `/codeaudit --files=... --focus=<area>` + `/debugaudit --url=... --files=...` |
+| "build is slow" | `/perfaudit` (solo) |
+| "security concern" on endpoint | `/apiaudit --url=... --focus=auth` → if findings → `/secaudit --url=...` |
+| "redesign the dashboard" | `/uiuxaudit` + `/flowaudit` + `/a11yaudit` (parallel) |
+| "audit everything" / "full audit" / "audit complet" | All 14 via Group 1→2 + Group 3 parallel |
+| "check accessibility" | `/a11yaudit` (solo) |
+| "SEO review" | `/perfaudit` then `/seoaudit` |
+| Linear ticket (rule 43) | Quadruple: `/codeaudit` + `/uiuxaudit` + `/flowaudit` + `/debugaudit` — all --ticket-scoped |
+| "audit the commands" / "audit the audits" | `/metaudit` (solo) |
+| "check if my CLI has UX issues" | `/dxaudit` + `/copyaudit` (NEVER `/uiuxaudit` on a CLI) |
+
+Full routing table: `~/.claude/commands/ARSENAL-ORCHESTRATION-PLAYBOOK.md`.
+
+---
+
+## 9. THE META-LAW
+
+> **One doctrine, fourteen implementations, zero drift, fifteen lenses when /metaudit is included.**
+
+- One `QUALITY-ARSENAL-PREAMBLE.md` (shared doctrine)
+- Fourteen audit `.md` files (each with compliance block + 100/100 certificate)
+- One `ARSENAL-INTERCONNECTIONS.md` (this file — relationships)
+- One `ARSENAL-ORCHESTRATION-PLAYBOOK.md` (how to dispatch)
+- One `/metaudit` command (compliance enforcement)
+
+Together: **a coherent Quality Arsenal, not 14 isolated tools.**
+
+---
+
+*v1.0 — 2026-04-14. Referenced by all audits, /metaudit, /aisb, /godmode, rule 43, rule 001.*
+
+---
+
+## 10. SIGNAL-BASED AUTO-DISPATCH (intelligence upgrade — preamble v1.1 §16)
+
+Beyond keyword matching, Oracle reads project signals before dispatching:
+
+```
+package.json deps detected → auto-focus
+  convex       → /dataaudit (Convex schema), /apiaudit (Convex functions)
+  @clerk/*     → /secaudit --focus=auth, /flowaudit --focus=auth-flow
+  stripe       → /flowaudit --focus=payment, /secaudit --focus=payment-security
+  next-intl    → /copyaudit --focus=i18n, /a11yaudit --focus=rtl
+  framer-motion → /motionaudit relevant
+  prisma       → /dataaudit + /apiaudit (schema → contract chain)
+  no react/vue → ABORT UI audits, route to /dxaudit + /copyaudit
+```
+
+Emit `project_signals_detected` in every verdict.json (preamble v1.1 §16).
+
+## 11. ARSENAL EXPANSION CANDIDATES
+
+Three gaps no current audit covers:
+
+| Proposed | Owns | Gap between |
+|----------|------|-------------|
+| /i18naudit | String extraction, locale completeness, date/number format, full RTL | /copyaudit (hardcoded strings) ↔ /a11yaudit (rendered locale) |
+| /cicdaudit | Build trends, DORA metrics, secret management, artifact caching | /dxaudit (static CI config) → runtime CI health |
+| /costaudit | Unbounded API calls, spend caps, runaway crons, serverless waste | No current audit covers billing exposure |
+
+Build when a project hits the gap. Not mandated.
+
+---
+
+*v1.1 — 2026-04-14. Added §10 signal-based dispatch + §11 expansion candidates.*