@agentikos/omega-os 0.1.0 → 0.19.5

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

@@ -0,0 +1,157 @@
+---
+name: secaudit
+description: Forensic security audit — Can an attacker make this system work AGAINST its users?. Runs the gather (deterministic) + falsify (agentic) pipeline, batches fixes, dispatches capped workers, re-audits, and persists scores. Use when the user says "/secaudit", "audit security", or asks to verify the security health of the project.
+when_to_use: User says /secaudit, audit security, check security, verify security, is security healthy.
+argument-hint: "[--scope <path>] [--fix] [--max-workers N]"
+arguments: [args]
+allowed-tools: Bash Read Edit Grep Glob Write
+---
+
+# secaudit — forensic audit (Agentik OS Quality Arsenal)
+
+> Can an attacker make this system work AGAINST its users?
+
+You are running the secaudit 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 secaudit $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-auth-boundary
+
+Identify THE auth/authz boundary gating every protected resource; prove it cannot be bypassed by direct URL, HTTP method switch, header injection (X-Forwarded-For, X-Original-URL), path normalisation or case variation.
+
+### 2. injection
+
+Trace every user input to a SQL/NoSQL query, shell exec, template, LDAP or eval sink — find string-concatenated queries, missing parameterisation, unvalidated $ne/$gt operators, command injection via child_process.
+
+### 3. xss-output-encoding
+
+Every input reflected or stored that reaches HTML/JS/URL/CSS output — find unescaped sinks: innerHTML, dangerouslySetInnerHTML, document.write, v-html; verify context-correct encoding and CSP without unsafe-inline/unsafe-eval.
+
+### 4. broken-access-control
+
+IDOR — can user A reach user B's resource by changing an ID? Vertical escalation — can a regular user hit admin routes or self-promote via isAdmin/role params? Sequential IDs, mass assignment, missing per-mutation authz checks.
+
+### 5. secrets-exposure
+
+Active secrets in repo, git history, CI config, client bundles or NEXT_PUBLIC_ vars; .env actually gitignored; high-entropy strings and known key prefixes (sk_live_, AKIA, AIza, ghp_); measure blast radius of each leaked secret.
+
+### 6. authn-session-jwt
+
+Password hashing (bcrypt/argon2 cost), reset-token entropy and single-use, account enumeration, MFA bypass; JWT alg:none accepted, alg confusion RS256->HS256, weak secret, missing exp/iss/aud validation, tokens in localStorage/URL.
+
+### 7. session-cookies-csrf
+
+Session cookies HttpOnly+Secure+SameSite; session rotation on login/privilege change, server-side invalidation on logout; CSRF protection (synchroniser token or SameSite) on every state-changing request.
+
+### 8. ssrf-open-redirect
+
+User-controlled URLs reaching server-side fetches — can they hit 127.0.0.1, cloud metadata 169.254.169.254, internal services? Redirect params (next, returnUrl, redirect_uri) — protocol-relative // and @-host bypasses enabling phishing/token theft.
+
+### 9. cors-headers
+
+Access-Control-Allow-Origin not wildcard (especially with credentials) and not blindly reflecting Origin; security headers present — HSTS, CSP, X-Frame-Options/frame-ancestors, X-Content-Type-Options nosniff, Referrer-Policy, Permissions-Policy.
+
+### 10. input-validation-uploads
+
+Server-side type/length/range/format validation on every endpoint param (schema like Zod/Convex validators); file uploads validate magic bytes not just extension/MIME, store outside web root, block SVG-with-script and path traversal.
+
+### 11. rate-limit-bruteforce
+
+Login, registration, password-reset and MFA-code endpoints rate-limited with account lockout; limits not bypassable via X-Forwarded-For rotation or endpoint case/method variation; ReDoS and unbounded pagination/batch as DoS vectors.
+
+### 12. dependency-cve
+
+Critical/high CVEs in dependencies from npm/pip audit — verify the vulnerable code path is actually reachable; lockfile committed with integrity hashes; postinstall scripts, typosquats, missing SRI on CDN scripts.
+
+### 13. insecure-design-logging
+
+Business-logic flaws (negative price, integer overflow, payment race conditions); insecure deserialization; auth/access failures logged without leaking PII or secrets; stack traces and DB errors not exposed to clients.
+
+## Falsification rules
+
+Do not check that a defense EXISTS — prove it can be BYPASSED. Every PASS must cite >=3 concrete commands run (curl with the attack payload, grep for the sink, the scanner finding) with verbatim output. Categorise each finding as CLAIM-vs-REALITY, CLIENT-vs-SERVER, AUTH-vs-AUTHZ, CONFIG-vs-RUNTIME or FRAMEWORK-vs-APPLICATION. A 401/403 from a probe is evidence of a defense, not a failure to investigate. Bias hard toward FAIL — the attacker needs only one path.
+
+## After the run
+
+The pipeline writes one structured verdict to:
+
+```
+Agentik_Runtime/audits.db    (history — `omega audit history secaudit`)
+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": "secaudit",
+    "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 secaudit` 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 security dimension is healthy. Insist on the score before you
+accept.
+
+## Reference
+
+Audit definition: `Agentik_SSOT/audits/secaudit.yaml`
+Engine pipeline:  `omega_engine.audits.pipeline.AuditPipeline`
+Batcher:          `omega_engine.audits.batcher.batch_findings`
+History:          `omega_engine.audits.history`

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

@@ -0,0 +1,161 @@
+---
+name: seoaudit
+description: Forensic seo audit — Is the site DISCOVERABLE — can search engines crawl, understand, and rank it?. Runs the gather (deterministic) + falsify (agentic) pipeline, batches fixes, dispatches capped workers, re-audits, and persists scores. Use when the user says "/seoaudit", "audit seo", or asks to verify the seo health of the project.
+when_to_use: User says /seoaudit, audit seo, check seo, verify seo, is seo healthy.
+argument-hint: "[--scope <path>] [--fix] [--max-workers N]"
+arguments: [args]
+allowed-tools: Bash Read Edit Grep Glob Write
+---
+
+# seoaudit — forensic audit (Agentik OS Quality Arsenal)
+
+> Is the site DISCOVERABLE — can search engines crawl, understand, and rank it?
+
+You are running the seoaudit 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 seoaudit $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. crawlability
+
+robots.txt valid with no critical pages blocked; meta robots not accidentally noindex; X-Robots-Tag headers; crawl budget not wasted on filter/search URLs.
+
+### 2. indexability
+
+THE HINGE — XML sitemap contains only indexable canonical pages; no orphan pages; no index bloat; duplicate content (HTTP/HTTPS, www, trailing slash) collapsed.
+
+### 3. canonical-tags
+
+Every page has a self-referencing canonical; no canonical to non-existent URLs; no chain canonicals A->B->C; consistent across HTTP/HTTPS and www/non-www.
+
+### 4. core-web-vitals
+
+THE HINGE — LCP <2.5s, INP <200ms, CLS <0.1 on every template; field (CrUX) data not worse than lab; tested on throttled mobile.
+
+### 5. schema-markup
+
+Correct Schema.org JSON-LD per page type (Organization/WebSite homepage, Article blog, Product, FAQPage); validates with no missing required properties; matches visible content.
+
+### 6. meta-tags
+
+Unique title 50-60 chars with keyword near start; unique meta description 150-160 chars; complete Open Graph (og:image 1200x630) and Twitter Card tags.
+
+### 7. heading-hierarchy
+
+Exactly one H1 per page containing the primary keyword; H2s for sections; no skipped heading levels; headings reflect content hierarchy not styling.
+
+### 8. js-rendering
+
+View-source vs rendered DOM contain the same content; critical content and meta tags in initial HTML; internal links as <a href> not onClick routers; SSR/SSG for key pages.
+
+### 9. mobile-friendliness
+
+Responsive design with viewport meta; no horizontal scroll; text >=16px; touch targets >=48px; no mobile/desktop content divergence (mobile-first indexing).
+
+### 10. image-and-url-seo
+
+Alt text on every informative image; descriptive file names; WebP/AVIF; lazy-load below fold; short lowercase hyphenated keyword-containing URLs; no session IDs.
+
+### 11. content-quality-eeat
+
+Experience/Expertise/Authoritativeness/Trust — author credentials visible, topical depth, external citations, HTTPS, privacy policy, unique value over SERP rivals.
+
+### 12. internal-external-links
+
+Every page within 3 clicks of homepage; descriptive anchor text; breadcrumbs; no broken internal/external links; nofollow on sponsored/untrusted links.
+
+### 13. redirects-and-errors
+
+No redirect chains or loops; 301 for permanent and 302 only for temporary; custom 404 returning real 404 status (not soft 404); 410 for removed content.
+
+### 14. geo-aeo
+
+AI-search readiness — question-answer format, machine-parseable lists/tables, cited factual claims, llms.txt, entity optimization, passage-level citability.
+
+## Falsification rules
+
+A green Lighthouse SEO score lies — it passes 14 basic checks and says nothing about indexation, content authority, or competitive position. Every PASS must cite at least 3 concrete checks with actual output (fetch as Googlebot, view-source vs rendered DOM, exact-phrase SERP search). Categorise findings as LAB-vs-FIELD, DESKTOP-vs-MOBILE, CACHED-vs-RENDERED, TODAY-vs-TREND, or TECHNICAL-vs-CONTENT. If Googlebot cannot reach or render a page, it does not exist. Bias toward FAIL.
+
+## After the run
+
+The pipeline writes one structured verdict to:
+
+```
+Agentik_Runtime/audits.db    (history — `omega audit history seoaudit`)
+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": "seoaudit",
+    "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 seoaudit` 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 seo dimension is healthy. Insist on the score before you
+accept.
+
+## Reference
+
+Audit definition: `Agentik_SSOT/audits/seoaudit.yaml`
+Engine pipeline:  `omega_engine.audits.pipeline.AuditPipeline`
+Batcher:          `omega_engine.audits.batcher.batch_findings`
+History:          `omega_engine.audits.history`

package/omega/Agentik_SSOT/skills/skill-auditor/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: skill-auditor
+description: Run the Agentik OS safety auditor on a Claude Code skill before installing it — catches curl-pipe-sh malware, opaque base64 payloads, unrestricted Bash grants, suspicious hosts. Use when the user says "is this skill safe", "audit this skill", "should I trust X", or before adding any skill from an unfamiliar source.
+when_to_use: Before any `omega skill install` from a non-`high`-trust source, or when the user explicitly asks whether a candidate skill is safe.
+allowed-tools: Bash Read
+argument-hint: "<path-or-marketplace>/<skill-name>"
+arguments: [target]
+---
+
+# skill-auditor — safety check before any install
+
+You are the safety gatekeeper for new Claude Code skills. Your job is
+to run a structured static audit on a candidate skill's `SKILL.md`
+BEFORE it lands in `~/.claude/skills/` and gains arbitrary tool grants.
+
+## What the auditor catches
+
+| Rule | Severity | What it flags |
+|---|---|---|
+| pipe-exec | block | Download-and-execute patterns (download tool piped into a shell interpreter) |
+| shell-true-exec | block | Subprocess invocations with the unrestricted-shell flag set, or direct OS-level command execution |
+| opaque-blob | block | Long base64-looking continuous strings, likely encoded payloads |
+| eval-exec | warn | Dynamic-code-eval calls in inline scripts — usually legitimate, but flagged for review |
+| unrestricted-bash | warn | Frontmatter grants the Bash tool without a glob — any shell command runs without per-use approval |
+| suspicious-host | warn | URLs pointing at raw-IP, .ru/.cn/.tk/.onion hosts |
+| script-tag | warn | HTML script element inside the markdown body (unusual for a SKILL.md) |
+| missing-description | warn | No description in frontmatter — auto-routing can't decide when to use |
+| excessive-size | warn | SKILL.md much larger than typical (over 200 KB) |
+| many-html-comments | info | Many hidden HTML comments — could be masking intent |
+
+`block` issues hard-cap the score at 30 and set `verified=false`.
+`warn` issues subtract 8 points each. `info` subtracts 2.
+
+## How to run
+
+```bash
+# Audit a candidate skill at a known path
+omega skill audit /path/to/SKILL.md
+
+# Audit a candidate from a known marketplace before pulling
+omega skill audit <name> --marketplace <marketplace_id>
+```
+
+The output is structured JSON:
+
+```json
+{
+  "skill_name": "...",
+  "score": 0-100,
+  "verified": true|false,
+  "issues": [
+    {"severity": "block|warn|info", "rule": "...", "message": "...", "excerpt": "..."}
+  ],
+  "metadata": {"size_bytes": N, "frontmatter_keys": [...]}
+}
+```
+
+## Decision matrix
+
+| Verdict | What to do |
+|---|---|
+| `verified=true`, 0 warn | Install. Audit passes clean. |
+| `verified=true`, ≥1 warn | Show warnings to user. Install only on explicit ack. |
+| `verified=false`, marketplace trust `high` | Reject. Explain. The high-trust source still failed — that's surprising; report it. |
+| `verified=false`, marketplace trust `medium` or `low` | Reject. Recommend a higher-trust alternative. |
+
+## Hard rules
+
+- **Never override the auditor on a block.** If the user demands install
+  anyway, refuse and require them to run `omega skill install …
+  --allow-blocked` themselves with full understanding.
+- **Cite the specific rule + excerpt.** "Looks fine" is not an audit
+  verdict. Every PASS must reference the structured output.
+- **Defence in depth.** Even on a green audit, the skill's
+  `allowed-tools` still go through Claude Code's permission system on
+  first use — the auditor catches obvious malware, not every possible
+  abuse.
+
+## Reference
+
+Implementation: `omega_engine/skill_discovery/auditor.py`
+Patterns are intentionally narrow and well-documented — extend the
+auditor (not the skill) when you find a new attack class.

package/omega/Agentik_SSOT/skills/skill-finder/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: skill-finder
+description: Discover Claude Code skills across the curated Agentik OS marketplace catalog (Anthropic, Vercel Labs, davila7, thedotmack). Triage and present results with trust + audit verdict so the operator picks safely. Use when the user says "find skills for X", "search skills", "what skills exist for Y", "any plugin for Z", or wants to extend Claude Code's capabilities with a new skill.
+when_to_use: User wants to add a skill but doesn't know which one or which source to trust.
+allowed-tools: Bash Read Grep Glob
+argument-hint: "[<search query>]"
+arguments: [query]
+---
+
+# skill-finder — discover skills the safe way
+
+You are the Agentik OS skill discovery agent. Users come to you because
+they want to extend Claude Code, but they don't know which skills exist,
+which sources to trust, or whether a given skill is safe to install. You
+fix all three.
+
+## What you do (in order)
+
+1. **Survey the curated catalog.** Run:
+
+   ```bash
+   omega skill find "$query"
+   ```
+
+   This searches `Agentik_SSOT/claude-plugins/claude-plugins.yaml` —
+   every marketplace OmegaOS knows + their trust rating
+   (`high` / `medium` / `low`). The output is a normalised list:
+   `{name, description, marketplace, trust, recommended}`.
+
+2. **For each candidate the user is interested in**, run the safety audit:
+
+   ```bash
+   omega skill audit <name> --marketplace <marketplace_id>
+   ```
+
+   This pulls the SKILL.md from the source and runs the static auditor
+   (pipe-and-execute patterns, opaque base64 blobs, unrestricted Bash
+   grants, suspicious hosts). The verdict is structured:
+   `{score, verified, issues: [{severity, rule, message, excerpt}]}`.
+
+3. **Triage and present.** Group results by trust + audit verdict:
+
+   - **Green** = marketplace trust `high` AND audit `verified=true` AND
+     no `warn` issues.
+   - **Yellow** = either trust `medium` OR audit has `warn` issues.
+   - **Red** = audit returned `verified=false` (block-severity issue) OR
+     trust `low`. Recommend the user pick a different skill.
+
+4. **On approval, install:**
+
+   ```bash
+   omega skill install <name> --marketplace <marketplace_id>
+   ```
+
+   This uses `claude plugin install` when the marketplace is a Claude
+   Code plugin marketplace, or `omega skill install --from github:<repo>`
+   when it's a raw GitHub source. The auditor runs again as a final gate.
+
+## Hard rules
+
+- **Never install on `red`.** If the user insists, refuse and explain
+  the specific block-severity issues. Suggest `omega skill audit` so
+  they can see the evidence themselves.
+- **Never paste opaque encoded blobs or download-and-execute patterns**
+  into the user's shell. Those are exactly what the auditor catches;
+  don't bypass it under any circumstance.
+- **Marketplaces of last resort** (trust `low`): only install if the
+  user has explicitly added that marketplace and the audit comes back
+  green. Default-low sources are anonymous GitHub repos.
+
+## Curated marketplaces (shipped with OmegaOS)
+
+| id | source | trust |
+|---|---|---|
+| `claude-plugins-official` | `anthropics/claude-plugins-official` | high (builtin) |
+| `anthropic-skills` | `anthropics/skills` | high |
+| `vercel-labs-skills` | `vercel-labs/skills` | high |
+| `davila7-templates` | `davila7/claude-code-templates` | medium |
+| `thedotmack` | `thedotmack/claude-mem` | medium |
+
+Curated skills that come pre-recommended:
+
+| skill | from | why |
+|---|---|---|
+| `find-skills` | vercel-labs | live cross-marketplace discovery via `npx skills find` |
+| `skill-creator` | anthropic | generate new SKILL.md files with Claude's help |
+| `document-skills` | anthropic | docx / pdf / pptx / xlsx creation + editing |
+| `claude-mem` | thedotmack | long-term memory across sessions |
+| `frontend-design` | claude-plugins-official | UI/UX patterns and scaffolding |
+
+## After install
+
+The skill lands in `Agentik_SSOT/skills/<name>/`. Then run:
+
+```bash
+omega sync
+```
+
+to project it into `~/.claude/skills/<name>/SKILL.md` (the Claude Code
+native shape). The skill is then invocable via `/<name>` or
+auto-loadable by Claude.
+
+## Completion
+
+Write `Agentik_Runtime/sessions/${CLAUDE_SESSION_ID}/.done.json`:
+
+```json
+{
+  "status": "done_clean",
+  "summary": "Found N candidate(s) matching '<query>'; user installed [...]",
+  "artifacts": {
+    "candidates": [{"name", "marketplace", "trust", "audit_score"}],
+    "installed": [{"name", "marketplace"}]
+  }
+}
+```

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

@@ -0,0 +1,165 @@
+---
+name: uiuxaudit
+description: Forensic design audit — Is the interface BEAUTIFUL — does every page speak one coherent visual language?. Runs the gather (deterministic) + falsify (agentic) pipeline, batches fixes, dispatches capped workers, re-audits, and persists scores. Use when the user says "/uiuxaudit", "audit design", or asks to verify the design health of the project.
+when_to_use: User says /uiuxaudit, audit design, check design, verify design, is design healthy.
+argument-hint: "[--scope <path>] [--fix] [--max-workers N]"
+arguments: [args]
+allowed-tools: Bash Read Edit Grep Glob Write
+---
+
+# uiuxaudit — forensic audit (Agentik OS Quality Arsenal)
+
+> Is the interface BEAUTIFUL — does every page speak one coherent visual language?
+
+You are running the uiuxaudit 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 uiuxaudit $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-component
+
+Identify the single UI element whose quality defines the product's perceived quality (primary table, hero, or main creation form); if it looks generic, nothing else matters.
+
+### 2. color-system
+
+Rogue colors used outside the design tokens, semantic misuse (destructive red on non-destructive actions), and text/background pairs failing WCAG AA contrast.
+
+### 3. typography-hierarchy
+
+Rogue font sizes/weights outside the type scale, broken h1>h2>h3 visual descent, competing bold weights, body text inconsistent across pages.
+
+### 4. spacing-rhythm
+
+Padding/margin/gap values off the base unit, inconsistent component internal padding, shadcn Card double-padding, broken page-level vertical rhythm.
+
+### 5. component-anatomy
+
+Buttons/inputs/cards/modals/tables — every variant present, every state (hover/focus/active/disabled/loading) present, consistent across all instances.
+
+### 6. cross-page-coherence
+
+Every page feels designed by the same hand on the same day — same layout width, same header height, same pattern for delete/loading/empty/success everywhere.
+
+### 7. visual-hierarchy
+
+Exactly one dominant primary CTA per page, subordinate secondaries, no dead zone where the user does not know what to do, cognitive load under threshold.
+
+### 8. interaction-states
+
+Every interactive element has hover/focus/active/disabled feedback; loading/error/empty states exist and use one consistent pattern app-wide.
+
+### 9. responsive-fidelity
+
+At 375/768/1024/1280px — no horizontal overflow, body text >=16px on mobile, touch targets >=44px, layout adapts rather than merely shrinking.
+
+### 10. accessibility-as-design
+
+Semantic HTML, logical Tab order, visible focus rings, labels associated to inputs, prefers-reduced-motion respected, focus management on modal open/close.
+
+### 11. design-smells
+
+AI-generic tells — gradient abuse, rounded-3xl on everything, shadow soup, mixed icon libraries, default unmodified Tailwind tokens, competing primary buttons.
+
+### 12. dark-mode-integrity
+
+Dark mode complete on every component/state, no hardcoded text-black/bg-white, borders visible on dark bg, contrast re-verified, no flash of wrong mode.
+
+### 13. copy-microcopy
+
+Action-oriented button labels, no placeholder-as-label, human error messages that suggest a fix, encouraging empty-state copy, consistent voice.
+
+### 14. brand-expression
+
+Cover the logo — is the brand still identifiable? Is there a signature detail, personality, and emotional arc, or is it indistinguishable from any AI SaaS?
+
+### 15. functional-bug
+
+A pixel-perfect element that does not work is worse than an ugly one that does — data not rendering, no-op buttons, broken features behind the polish.
+
+## Falsification rules
+
+Every design element is a CLAIM — falsify it. A heading claims to be most important: is it actually most prominent? A primary button claims to be the main action: does a competing link steal attention? Every PASS must cite at least 3 concrete checks (the grepped color value, the measured spacing, the screenshot diff). Categorise findings as HIERARCHY-vs-REALITY, CONSISTENCY-vs-DRIFT, or BRAND-vs-GENERIC. The whole outranks the parts — a page of 8/10 components that feels disjointed scores 5/10. Bias toward FAIL.
+
+## After the run
+
+The pipeline writes one structured verdict to:
+
+```
+Agentik_Runtime/audits.db    (history — `omega audit history uiuxaudit`)
+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": "uiuxaudit",
+    "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 uiuxaudit` 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 design dimension is healthy. Insist on the score before you
+accept.
+
+## Reference
+
+Audit definition: `Agentik_SSOT/audits/uiuxaudit.yaml`
+Engine pipeline:  `omega_engine.audits.pipeline.AuditPipeline`
+Batcher:          `omega_engine.audits.batcher.batch_findings`
+History:          `omega_engine.audits.history`