@agentikos/omega-os 0.1.0 → 0.19.5

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/marketplaces/design-discipline.yaml

@@ -0,0 +1,86 @@
+# Design-discipline skill marketplace
+#
+# Curated catalog of design skills OmegaOS expects to be installed
+# globally on the host. The installer (step 25-aisb-suite or
+# `omega design install`) pulls each one and lands it under
+# ~/.claude/skills/<id>/.
+#
+# These are NOT OmegaOS-authored skills — they're upstream skills the
+# OmegaOS contract REQUIRES because Genesis writes feature briefs that
+# reference them by name (skill: "/shadcn-ui + /emil-design-eng + …").
+#
+# Update protocol: bump the source SHA when the upstream skill ships a
+# breaking change. Workers see the new content on the next `omega sync`.
+
+version: 1
+kind: design-discipline
+recommended_for_roles: [worker_ui, worker_growth]
+skills:
+  - id: shadcn-ui
+    source: bundled                          # bundled with Claude Code
+    discovery: "/shadcn-ui"
+    purpose: "Every component from https://ui.shadcn.com/docs/components"
+    required: true
+
+  - id: emil-design-eng
+    source: "github:emilkowalski/skill"
+    install: "npx skills add emilkowalski/skill"
+    discovery: "/emil-design-eng"
+    purpose: "Design engineering discipline — tactile, motion-aware, subtle"
+    why: "Sets the bar for what 'good design' means at the engineering layer."
+    required: true
+
+  - id: impeccable
+    source: "github:pbakaus/impeccable"
+    install: "npx skills add pbakaus/impeccable"
+    discovery: "/impeccable"
+    purpose: "Pixel-level craft — no half-baked components, no inconsistent spacing"
+    why: "Catches the gap between 'works' and 'feels finished'."
+    required: true
+
+  - id: taste-skill
+    source: "github:Leonxlnx/taste-skill"
+    install: "npx skills add Leonxlnx/taste-skill"
+    homepage: "https://www.tasteskill.dev"
+    discovery: "/taste-skill"
+    purpose: "Taste calibration across typography, colour, hierarchy, motion"
+    required: true
+
+  - id: frontend-design
+    source: bundled                          # Anthropic-bundled
+    discovery: "/frontend-design"
+    purpose: "High-quality production-grade frontend code generator"
+    required: false
+
+  - id: design-taste-frontend
+    source: bundled
+    discovery: "/design-taste-frontend"
+    purpose: "Taste applied at the frontend layer"
+    required: false
+
+  - id: gpt-taste
+    source: bundled
+    discovery: "/gpt-taste"
+    purpose: "Taste comparison + improvement"
+    required: false
+
+# Components — every shadcn component is in scope by default for any
+# UI feature. Workers should reference these by name.
+shadcn_components:
+  scope: "everything at https://ui.shadcn.com/docs/components"
+  ranked_for_v1:
+    - button
+    - card
+    - input
+    - select
+    - dialog
+    - sheet
+    - tabs
+    - toast
+    - tooltip
+    - dropdown-menu
+    - command
+    - form
+    - data-table
+    - calendar
+    - popover

package/omega/Agentik_SSOT/skills/a11yaudit/SKILL.md

@@ -0,0 +1,161 @@
+---
+name: a11yaudit
+description: Forensic accessibility audit — Can EVERYONE use it — keyboard-only, screen reader, low vision, reduced motion?. Runs the gather (deterministic) + falsify (agentic) pipeline, batches fixes, dispatches capped workers, re-audits, and persists scores. Use when the user says "/a11yaudit", "audit accessibility", or asks to verify the accessibility health of the project.
+when_to_use: User says /a11yaudit, audit accessibility, check accessibility, verify accessibility, is accessibility healthy.
+argument-hint: "[--scope <path>] [--fix] [--max-workers N]"
+arguments: [args]
+allowed-tools: Bash Read Edit Grep Glob Write
+---
+
+# a11yaudit — forensic audit (Agentik OS Quality Arsenal)
+
+> Can EVERYONE use it — keyboard-only, screen reader, low vision, reduced motion?
+
+You are running the a11yaudit forensic audit. Apply the **Gestalt-Popper
+doctrine**: identify the hinge point, scrutinise it 10x, then assume
+every name is a CLAIM and look for the divergence between the claim and
+the reality. Bias toward FAIL. A perfect score is earned by finding zero
+falsifiable claims, never by absence of effort.
+
+## Run
+
+The audit is one engine call — gather (deterministic) + falsify (agentic)
++ optional fix-dispatch (capped) + re-audit. Invoke the unified pipeline:
+
+```bash
+omega audit run a11yaudit $args
+```
+
+Common options:
+
+| Flag | Effect |
+|---|---|
+| `--scope <path>` | scope the audit (file or directory) |
+| `--fix` | after analysing, batch findings + dispatch up to N workers + re-audit |
+| `--max-workers N` | cap parallel fix workers (default 3) |
+| `--min-severity high` | only batch + fix findings at or above this severity |
+
+Read-only by default. Add `--fix` to enable the dispatch + re-audit loop.
+
+## Phases under investigation
+
+The agentic pass walks each phase below and emits structured findings
+(claim vs. reality). Every PASS must cite ≥3 concrete checks.
+
+### 1. hinge-keyboard-navigation
+
+HINGE — disconnect the mouse and complete the primary user journey keyboard-only; logical tab order matching visual flow, no tabindex>0, no non-interactive element focusable; every button activates with Enter AND Space, links with Enter, Escape closes overlays.
+
+### 2. keyboard-traps-focus-visibility
+
+Focus can always escape every modal, dropdown, menu and date picker (no infinite tab loop); focus indicator ALWAYS visible, >=2px and >=3:1 contrast, in light/dark/high-contrast; no outline:none without a replacement.
+
+### 3. wcag-aa-compliance
+
+Per page verify WCAG 2.1 AA across the four principles — Perceivable, Operable, Understandable, Robust; lang attribute, valid HTML with no duplicate IDs, reflow at 320px, text resize to 200%; treat the 70% of failures automation misses as the real work.
+
+### 4. screen-reader-semantics
+
+Page title, headings, landmarks and list/table structure announced; buttons announce name+role, inputs announce label+type+state; reading order matches visual layout; nothing meaningful hidden from the screen reader, nothing decorative announced.
+
+### 5. aria-correctness
+
+First rule of ARIA — if native HTML can do it, ARIA is wrong; custom widgets have correct roles with required children; aria-expanded/selected/checked/current reflect real state; aria-labelledby/describedby/controls reference existing visible elements; aria-hidden never hides visible content.
+
+### 6. semantic-elements
+
+Interactive things are real <button>/<a>/<input>, not <div onClick>; landmark elements (<main> once, <nav>, <header>, <footer>) present, labelled when repeated, and wrap all visible content with no orphans.
+
+### 7. color-contrast
+
+Normal text >=4.5:1, large text >=3:1 against every background it sits on (including over images/gradients and placeholder text); UI component borders, focus rings and meaningful icons >=3:1; verify in dark mode and forced-colors.
+
+### 8. color-independence
+
+No information conveyed by colour alone — links distinguishable without colour (underline/weight), required fields marked with text/asterisk, errors carry icon+text not just red; grayscale the page and confirm nothing is lost.
+
+### 9. form-labels-and-instructions
+
+Every input has a programmatic label (label/aria-label/aria-labelledby), placeholder is never the only label; correct input types and autocomplete on personal-data fields; required fields marked visually AND with aria-required; instructions precede the form; related inputs grouped with fieldset/legend.
+
+### 10. error-announcements
+
+Inline errors associated via aria-describedby/aria-errormessage and announced without reload, field marked aria-invalid; on submit failure an error summary appears, focus moves to it, error count announced; success confirmed via aria-live; destructive actions confirm and warn of data loss.
+
+### 11. alt-text
+
+Informative images have descriptive alt conveying content+purpose; decorative images have alt="" (empty, not missing) and decorative icons aria-hidden; functional/image links/buttons describe the destination or action; complex charts have a text or data-table alternative; SVGs labelled or hidden.
+
+### 12. heading-hierarchy-skip-nav
+
+Exactly one <h1>, no skipped levels, headings describe content and are not styled-div fakes; a 'Skip to main content' link is the first focusable element, visible on focus, and lands on a valid landmark/heading.
+
+### 13. focus-management
+
+Focus starts at a logical position on load and moves to new content on SPA route change (with page-title update); modals move focus in on open and return it to the trigger on close; deleted content moves focus to a logical neighbour; focus never silently lost to <body>.
+
+### 14. motion-and-touch-targets
+
+@media (prefers-reduced-motion: reduce) honoured by CSS and JS animations; no auto-playing audio ever, video/carousels have pause, nothing flashes >3x/sec; interactive targets >=44x44px CSS with >=8px spacing, checked at the smallest mobile viewport.
+
+## Falsification rules
+
+Automated tools catch ~30% of failures — a "0 violations" report means 70% are INVISIBLE to automation, not absent. Every PASS must cite >=3 concrete manual checks (keyboard-only walkthrough of the flow, computed contrast ratio, grayscale test, prefers-reduced-motion toggle) with verbatim observations. Categorise findings as VISUAL-vs-SEMANTIC, MOUSE-vs-KEYBOARD, SIGHTED-vs-SCREEN-READER, DESKTOP-vs-MOBILE or DEFAULT-vs-PREFERENCE. An axe-core contrast finding near the 4.5 threshold must be confirmed by computing the exact ratio. Bias toward FAIL — the excluded users never complained.
+
+## After the run
+
+The pipeline writes one structured verdict to:
+
+```
+Agentik_Runtime/audits.db    (history — `omega audit history a11yaudit`)
+Agentik_Runtime/sessions/${CLAUDE_SESSION_ID}/.done.json   (this turn)
+```
+
+The `.done.json` schema:
+
+```json
+{
+  "status": "done_clean" | "pending" | "failed",
+  "summary": "<one-paragraph verdict>",
+  "artifacts": {
+    "audit": "a11yaudit",
+    "score": 0-100,
+    "verified": bool,
+    "findings": [...],
+    "fix_plan": [...],
+    "dispatches": [...],
+    "reaudit_score": 0-100  // only when --fix was used
+  }
+}
+```
+
+## Hard rules (don't break these)
+
+1. **No fake "done".** First Law: only runtime tells the truth. If the
+   gather phase fails or the agentic verdict scores below the threshold,
+   you have NOT verified — set status to `pending` or `failed`.
+2. **Cap parallelism.** ≤ 3 fix workers at a time. The
+   batcher enforces this; do not call out to other dispatch mechanisms.
+3. **No worker per finding.** Findings are clustered by file footprint and
+   severity. One worker handles one disjoint batch.
+4. **Re-audit confirms.** After fixes land, the pipeline re-runs the same
+   gather + agentic phases. If the score did not improve, escalate honestly.
+5. **History is the trend.** `omega audit history a11yaudit` shows whether the
+   codebase is improving over time on this dimension. Use it to decide
+   whether to push for `--fix` again.
+
+## Why this audit exists
+
+The 18 forensic audits are the OmegaOS verification layer. Claude's
+"I'm done" claims used to be unverified. With these audits running as
+the gate, completion is **derived from observable facts**, not declared
+by the worker. Run this audit any time someone (human or agent) claims
+the accessibility dimension is healthy. Insist on the score before you
+accept.
+
+## Reference
+
+Audit definition: `Agentik_SSOT/audits/a11yaudit.yaml`
+Engine pipeline:  `omega_engine.audits.pipeline.AuditPipeline`
+Batcher:          `omega_engine.audits.batcher.batch_findings`
+History:          `omega_engine.audits.history`