@agentikos/omega-os 0.2.0 → 0.19.6

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

@@ -0,0 +1,165 @@
+---
+name: refontaudit
+description: Forensic redesign audit — Is there a ship-ready refonte plan — does it preserve what works and fix only what data proves broken?. Runs the gather (deterministic) + falsify (agentic) pipeline, batches fixes, dispatches capped workers, re-audits, and persists scores. Use when the user says "/refontaudit", "audit redesign", or asks to verify the redesign health of the project.
+when_to_use: User says /refontaudit, audit redesign, check redesign, verify redesign, is redesign healthy.
+argument-hint: "[--scope <path>] [--fix] [--max-workers N]"
+arguments: [args]
+allowed-tools: Bash Read Edit Grep Glob Write
+---
+
+# refontaudit — forensic audit (Agentik OS Quality Arsenal)
+
+> Is there a ship-ready refonte plan — does it preserve what works and fix only what data proves broken?
+
+You are running the refontaudit 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 refontaudit $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. inventory
+
+Crawl every route in scope, screenshot at 1440/1024/375px, map shadcn usage, extract font stack and palette; under 3 routes or no shadcn means wrong project — abort.
+
+### 2. current-ia
+
+Build the IA tree (sidebar -> pages -> sub-pages -> modals), classify each screen (list/detail/form/overview/settings/empty), flag orphaned screens and nav-to-nothing stubs.
+
+### 3. current-flows
+
+Trace the top 5 user intents from dashboard to completed action; count clicks to primary action, context switches, waiting states; mark friction (>3 clicks, modal-in-modal, full reloads).
+
+### 4. density-hierarchy
+
+Per top-level screen measure items-per-viewport, visual hierarchy depth, primary-action clarity (yes/no/ambiguous), whitespace ratio — density is a feature only with clear hierarchy.
+
+### 5. data-collection
+
+Read real data before redesigning — Linear ticket hotspots per page, console-error hotspots, analytics if configured, git-churn hotspots; the top 3 pages are the priority targets.
+
+### 6. user-story-mining
+
+Extract 10 user stories (as-a/I-want/so-that) with frequency and friction; prioritize by frequency x friction into P1/P2/P3; this list drives every later proposal.
+
+### 7. keep-audit
+
+The hinge of restraint — classify EVERY screen KEEP (works, untouchable) / IMPROVE (good bones, targeted change) / RETHINK (wrong approach) / KILL (no story, no traffic, orphan).
+
+### 8. clarity-gate
+
+5-second Gestalt test per screen — can the user answer 'what is this page for?' and 'what is the primary action?'; score pass/partial/fail; compute current clarity percentage.
+
+### 9. hypothesis-falsification
+
+Generate 3 data-grounded hypotheses for why the design fails (worst ticket-hotspot page, worst-friction P1 story, worst clarity screen); only hypotheses that survive falsification become rationale.
+
+### 10. pattern-mapping
+
+For each high-friction P1/P2 story match a proven pattern from real reference products (Linear/Vercel/Stripe), grounded in the user story it serves — not 'it looks nice'; flag gaps needing custom solutions.
+
+### 11. ia-proposal
+
+The hinge — name the 3-5 specific evolution changes resolving 80% of friction (each citing a user story + data + reference); never change the nav model unless >50% of screens are RETHINK.
+
+### 12. workflow-redesign
+
+For each P1 story show before/after click count and context switches with happy path plus 2 edge cases; redesign only flows touching IMPROVE/RETHINK screens, never KEEP screens.
+
+### 13. component-composition
+
+Map each new/improved page to a real shadcn component tree with typed composite interfaces; KEEP screens get no new components — this prevents 'while we're here' scope creep.
+
+### 14. interaction-state-model
+
+Define keyboard grammar, hover/focus rules, empty/loading/error patterns, and the state architecture (URL vs server vs UI vs selection) so shared links and the back button restore exact state.
+
+### 15. hinge-stress-test
+
+Stress the top 3 proposed changes against 10 scenarios — new user/0 data, power user/10k items keyboard-only, mobile 375px, dark mode, long names, RTL, offline, interruption, screen reader, 1000-item lists.
+
+## Falsification rules
+
+A refonte without user stories is decoration; without data is guessing; without a Keep Audit is vandalism. FALSIFY every proposal — it must trace to a P1/P2 user story AND a measured hotspot, or its confidence collapses. Evolution beats revolution: a senior never reaches for revolution first. Categorise gaps as KEEP-TOUCHED (a working screen was redesigned — automatic fail), STORYLESS-PROPOSAL (change serving no user story), or HINGE-UNPROVEN (the 3-5 changes failed 2+ of the 10 scenarios). Every proposal carries an honest confidence score — nothing is 100%, senior humility. Bias toward FAIL.
+
+## After the run
+
+The pipeline writes one structured verdict to:
+
+```
+Agentik_Runtime/audits.db    (history — `omega audit history refontaudit`)
+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": "refontaudit",
+    "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 refontaudit` 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 redesign dimension is healthy. Insist on the score before you
+accept.
+
+## Reference
+
+Audit definition: `Agentik_SSOT/audits/refontaudit.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/retentionaudit/SKILL.md

@@ -0,0 +1,165 @@
+---
+name: retentionaudit
+description: Forensic retention audit — What would the CPO of a $1B SaaS find that we MISSED to make users stay 3x longer?. Runs the gather (deterministic) + falsify (agentic) pipeline, batches fixes, dispatches capped workers, re-audits, and persists scores. Use when the user says "/retentionaudit", "audit retention", or asks to verify the retention health of the project.
+when_to_use: User says /retentionaudit, audit retention, check retention, verify retention, is retention healthy.
+argument-hint: "[--scope <path>] [--fix] [--max-workers N]"
+arguments: [args]
+allowed-tools: Bash Read Edit Grep Glob Write
+---
+
+# retentionaudit — forensic audit (Agentik OS Quality Arsenal)
+
+> What would the CPO of a $1B SaaS find that we MISSED to make users stay 3x longer?
+
+You are running the retentionaudit 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 retentionaudit $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-capability
+
+THE HINGE — identify the ONE experience that must be world-class for users to stay; compare STATED hinge (copy) vs OBSERVED hinge (where code/commits invest); a divergence is the single most damaging retention bug.
+
+### 2. user-journey
+
+Trace every screen from sign-up to power-user; map transitions, entry and exit conditions; this journey feeds the drop-off forensics.
+
+### 3. drop-off-forensics
+
+Per screen identify likely churn triggers — unvalidated forms, loaders without progress, blank empty states, blocking modals, auth/pricing walls before perceived value.
+
+### 4. aha-moment-latency
+
+Identify the moment a new user goes 'now I get it'; how many steps from signup to aha; what blocks the users who never reach it.
+
+### 5. hooked-loops
+
+Eyal lens — for each retention-driving feature score the 4 elements Trigger/Action/Variable-Reward/Investment; 4/4 strong, <=2/4 no loop.
+
+### 6. jobs-to-be-done
+
+Christensen lens — per persona surface 3-5 jobs ('When [situation] I want to [job] so I can [outcome]'); does the product serve each job, or does the user hire a competitor/workaround?
+
+### 7. personalization-debt
+
+Per screen/feed/list — is order user-specific or global, are recommendations history-based, are defaults adapted (timezone, recently-used); generic feed = anyone could leave.
+
+### 8. onboarding-completeness
+
+The first 7 days set LTV — welcome/checklist, first-task guidance, teaching empty states, day-1/3/7 nudges, measurable activation criteria; onboarding must DELIVER value not teach the UI.
+
+### 9. empty-states
+
+Every component that renders with no data must teach + invite + commit (3 elements); a blank rectangle is malpractice; empty-state CTAs must reach value in one step.
+
+### 10. power-of-moments
+
+Heath lens — audit peaks (amplify), pits (fix/remove), transitions (mark with ceremony), plateaus (interrupt with surprise); 'fine but never memorable' products churn.
+
+### 11. network-effects
+
+One-click invite of a teammate/friend; does the product get MORE valuable as N users join; public shareable artifacts/embeds; compounding UGC.
+
+### 12. monetization-hooks
+
+Value-gate placed after aha and before commitment; upgrade trigger contextual (limit reached) not nag-banner; price anchor visible early; clear team-plan path.
+
+### 13. reactivation-flows
+
+Win-back for dormant users — D3/D7/D14/D30/D90 email cadence, 'what you missed' digest, value-first re-engagement (never dark-pattern FOMO).
+
+### 14. discoverability-and-power-user
+
+Are powerful features hidden — command-palette completeness, settings organization, changelog visibility; for the top 1% propose keyboard shortcuts, bulk ops, API/export.
+
+### 15. prioritized-roadmap
+
+Synthesise all proposals into a RICE-scored list, then Fogg B=MAT (M x A x T) on the top 15; priority = RICE_normalized x (1 + Fogg/27); flag high-RICE/low-Fogg ideas and anti-patterns (vanity hooks, dark patterns, shallow personalization, feature bloat).
+
+## Falsification rules
+
+The product implicitly claims users will stick — DISPROVE it. Find every reason a smart user would churn after week 1, month 1, month 3. Every claim and every proposed opportunity must cite at least 3 concrete checks with actual output (grep proving a drop-off friction exists, a competitor URL proving a parity gap). "Probably broken" / "competitors all" / "users likely" without evidence is an automatic FAIL of the finding. Engagement is not retention — score every proposal against month-3 retention, not DAU. This audit is READ-ONLY: it proposes and ranks, it never codes — implementation is a separate authorized mission.
+
+## After the run
+
+The pipeline writes one structured verdict to:
+
+```
+Agentik_Runtime/audits.db    (history — `omega audit history retentionaudit`)
+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": "retentionaudit",
+    "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 retentionaudit` 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 retention dimension is healthy. Insist on the score before you
+accept.
+
+## Reference
+
+Audit definition: `Agentik_SSOT/audits/retentionaudit.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/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`