@agentikos/omega-os 0.1.0 → 0.19.5

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

@@ -0,0 +1,117 @@
+---
+name: handoff
+description: Write a 5-section session handoff memo so the next agent picks up cleanly with zero rediscovery. The five fields are MISSION (one sentence) / STATE (what works, what doesn't, with runtime evidence) / FILES TOUCHED (exact paths, no guessing) / DEAD ENDS (what was tried and failed, don't re-walk) / NEXT (first concrete action). Persists to HANDOFF.md at the project root (always-latest) + an archive copy under .omega/handoffs/<timestamp>. Use BEFORE /clear, BEFORE ending a tmux session, or when the user says "/handoff", "write a handoff", "fais un handoff", "termine la session", "memo de fin", "passe le relais", "hand off to the next agent".
+when_to_use: User is about to /clear, end a coding session, or wants the next agent to resume from a known state. Also when a long mission completes and the next phase will run in a fresh session.
+allowed-tools: Bash Read Write
+argument-hint: "[--project <slug>]"
+arguments: [project]
+---
+
+# handoff — session-end memo for the next agent
+
+You are writing a HANDOFF. The next agent (or the user's future-self) will
+read this and pick up EXACTLY where you stopped, without re-walking the
+same code, without re-running the same commands, without re-making the
+same mistakes.
+
+## The five fields (non-negotiable, in this order)
+
+### 1. Mission
+
+ONE sentence. What was this session trying to achieve? Not "we worked on
+auth"; rather "Implement OAuth login against `/api/auth/google` and make
+`tests/auth.test.ts` pass end-to-end."
+
+### 2. State (what works / what doesn't)
+
+Three concrete observations, each backed by runtime evidence:
+
+- **Works:** what is verifiable runtime? E.g. "sign-in flow redirects to
+  /dashboard, screenshot at `audits/.flowaudit/run-2026-05-24/auth.png`".
+- **Broken:** what fails right now? E.g. "/api/profile PATCH returns 500;
+  curl reproduces, console: TypeError at line 142".
+- **Verified by:** the COMMAND or URL that proves the claim. E.g.
+  "`npm test -- tests/auth.test.ts`" or "`curl https://app/api/health`".
+
+If you cannot back a claim with a runtime command, mark it as
+"observed-but-not-verified" — never lie.
+
+### 3. Files touched
+
+Every file you edited or created in THIS session. Exact paths, no
+guessing, no "the routes file". Use line numbers when only a slice
+mattered:
+
+    - `apps/web/src/routes/api/auth/google.ts`
+    - `apps/web/src/components/SignInForm.tsx:42-78`
+    - `tests/auth.test.ts`
+
+Run `git diff --name-only HEAD` if you're unsure — copy the output.
+
+### 4. Dead ends — DO NOT retry
+
+What was TRIED and DOESN'T work, so the next agent does not waste a
+session re-walking the same wall. Each bullet must say: what was tried,
+why it failed, what NOT to try again.
+
+    - Tried passing `accessToken` via Authorization header to Google's
+      `/userinfo` — got 401 because Google's lib expects it on the query
+      string. Don't re-route through the header.
+    - Tried `next-auth` v5 beta — incompatible with our pinned Next 14.0.
+      Don't suggest a v5 upgrade unless we also bump Next.
+
+If there were no dead ends, write "_(none)_". Don't pad with fake bullets.
+
+### 5. Next — start here
+
+The FIRST concrete action the next agent should take. Numbered, one item
+per line. Be specific:
+
+    1. Add `NEXTAUTH_SECRET` to `.env.local` (it's missing — see error in
+       state §2). Test: `npm run dev` should no longer print the warning.
+    2. Wire the new endpoint into `apps/web/src/app/api/auth/[...nextauth]/route.ts`.
+    3. Re-run `npm test -- tests/auth.test.ts`; should be 0 failures.
+
+If the next step is "ship it" or "merge", write that explicitly.
+
+## Run
+
+Build the handoff in memory, then write it via the engine:
+
+```bash
+# auto-draft from the worker's own .done.json + git diff
+omega handoff from-done $CLAUDE_SESSION_ID --project $project --print
+
+# or write a freshly-composed one (--file points to a markdown file
+# you just wrote that follows the 5-section template)
+omega handoff write --project $project --file /tmp/handoff-draft.md
+```
+
+The engine persists the markdown to:
+
+  - `$OMEGA_HOME/Agentik_Coding/projects/$project/HANDOFF.md`   (always-latest)
+  - `$OMEGA_HOME/Agentik_Coding/projects/$project/.omega/handoffs/<ts>.md`  (archive)
+
+The next session reads the latest with:
+
+```bash
+omega handoff read --project $project
+```
+
+## Quality gate (the protocol enforces this)
+
+Before exiting, re-read your handoff and ask:
+
+- Could a fresh agent execute step §5.1 with ZERO additional context? If
+  not, rewrite it.
+- Are all §3 file paths real (`test -e` returns 0 for every one)? If not,
+  remove the speculative ones.
+- Does §4 actually save the next agent time? If not, delete it.
+
+The handoff is load-bearing. A vague handoff is worse than no handoff —
+it costs the next agent more than it saves.
+
+---
+
+*Argument: `$project` (slug) — required so the handoff lands at the
+right project root.*

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

@@ -0,0 +1,165 @@
+---
+name: logicaudit
+description: Forensic logic audit — Where is the system fighting itself — wasted computation, redundant paths, the wrong amount of engineering?. Runs the gather (deterministic) + falsify (agentic) pipeline, batches fixes, dispatches capped workers, re-audits, and persists scores. Use when the user says "/logicaudit", "audit logic", or asks to verify the logic health of the project.
+when_to_use: User says /logicaudit, audit logic, check logic, verify logic, is logic healthy.
+argument-hint: "[--scope <path>] [--fix] [--max-workers N]"
+arguments: [args]
+allowed-tools: Bash Read Edit Grep Glob Write
+---
+
+# logicaudit — forensic audit (Agentik OS Quality Arsenal)
+
+> Where is the system fighting itself — wasted computation, redundant paths, the wrong amount of engineering?
+
+You are running the logicaudit 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 logicaudit $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. redundant-logic
+
+Semantically identical logic in 3+ places; checks repeated across middleware/handler/service (blurs who owns validation); overlapping modules; chained data transforms; self-defeating logic (cache invalidated before read).
+
+### 2. algorithmic-efficiency
+
+Real Big-O of every loop/recursion; O(n^2) hidden as Array.find inside Array.map; N+1 query/fetch patterns; unnecessary computation (sort just to test existence); string concat / regex compile in loops.
+
+### 3. pipeline-efficiency
+
+Sum of step times vs total pipeline time — overhead >50% means the pipeline design IS the bug; sequential steps with no data dependency; stages producing output nobody reads; restart-from-stage-1 vs checkpoint.
+
+### 4. orchestration-overhead
+
+Hop count user→result — which hops are essential vs ceremony; dispatch overhead vs task size (task < dispatch cost → do it in-place); intent preserved or diluted per hop; coordination tax in multi-agent work.
+
+### 5. abstraction-fit
+
+Over-abstraction (factory with one type, plugin system with one plugin, GenericHandler<T> always string); under-abstraction (15 lines copy-pasted 8×); wrong abstraction (UserService doing auth+billing+notifications).
+
+### 6. state-machines
+
+Implicit state from combined booleans (isLoading+hasError+isReady = impossible combos); states that CAN be represented but are impossible WILL be reached; missing transitions (Loading with no path to Error).
+
+### 7. data-flow-entropy
+
+Single source of truth per datum (same data in DB + local state + URL = 3 truths); transformation chain length; data duplication without sync; prop drilling through components that never use it; stale-data patterns.
+
+### 8. caching-intelligence
+
+Missing caches (pure function re-called with same inputs, static reference data re-queried); ineffective caches (2% hit rate = wrong key granularity); invalidation correctness; caching at the right layer.
+
+### 9. parallelization-gaps
+
+Independent ops awaited serially instead of Promise.all; N individual calls that should be one batch; load-everything-then-process instead of streaming; worker pool sized wrong for wait/compute ratio.
+
+### 10. config-complexity
+
+Total config surface vs how many values are EVER changed from default; same value defined in .env AND config AND CLI AND default with undocumented precedence; invalid config caught at startup not first request.
+
+### 11. error-logic
+
+Swallowed errors (empty catch, .catch(()=>null)); error info loss (rethrow as generic 'something went wrong', logged at INFO); retry on non-transient 4xx; retry without backoff/idempotency/ceiling; wrong fallback values.
+
+### 12. decision-tree-pruning
+
+Arrow anti-pattern (if→if→if→if→logic) — flatten with guard clauses; 40-case switch that should be a lookup map; feature flags always-ON or always-OFF; routing that could be a simple table.
+
+### 13. over-engineering
+
+Unused flexibility (EventEmitter with one listener, strategy pattern with one strategy); premature optimization; architecture astronautics (microservices for one dev, event sourcing for CRUD); speculative generality.
+
+### 14. under-engineering
+
+Missing validation at boundaries (user input reaches DB unsanitized); missing error boundaries (one component crash kills the page); missing observability on critical paths; complex algorithm with zero comments.
+
+### 15. dead-logic
+
+Unreachable code after return/throw; branches guarded by always-true/false conditions; functions defined-never-called-not-exported; dead feature flags; commented-out code blocks; unused imports/variables.
+
+## Falsification rules
+
+Complexity is guilt until proven innocent — every abstraction, config layer and indirection must justify its existence with measurement or be eliminated. Every optimization claim is a hypothesis: "this cache speeds it up" → prove it with hit-rate numbers; "this abstraction reduces complexity" → count lines/branches before and after. Categorise findings as CLAIM-vs-MEASUREMENT, ABSTRACTION-vs-USAGE, CACHE-vs-FRESHNESS, PARALLEL-vs-SEQUENTIAL, RETRY-vs-IDEMPOTENT, or CONFIG-vs-HARDCODE. An optimization with no measurable improvement is a failed hypothesis — revert it.
+
+## After the run
+
+The pipeline writes one structured verdict to:
+
+```
+Agentik_Runtime/audits.db    (history — `omega audit history logicaudit`)
+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": "logicaudit",
+    "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 logicaudit` 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 logic dimension is healthy. Insist on the score before you
+accept.
+
+## Reference
+
+Audit definition: `Agentik_SSOT/audits/logicaudit.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/motionaudit/SKILL.md

@@ -0,0 +1,165 @@
+---
+name: motionaudit
+description: Forensic motion audit — Does it MOVE with purpose — does every animation earn its place and run at 60fps?. Runs the gather (deterministic) + falsify (agentic) pipeline, batches fixes, dispatches capped workers, re-audits, and persists scores. Use when the user says "/motionaudit", "audit motion", or asks to verify the motion health of the project.
+when_to_use: User says /motionaudit, audit motion, check motion, verify motion, is motion healthy.
+argument-hint: "[--scope <path>] [--fix] [--max-workers N]"
+arguments: [args]
+allowed-tools: Bash Read Edit Grep Glob Write
+---
+
+# motionaudit — forensic audit (Agentik OS Quality Arsenal)
+
+> Does it MOVE with purpose — does every animation earn its place and run at 60fps?
+
+You are running the motionaudit 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 motionaudit $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. motion-inventory
+
+Catalog every animation — CSS transitions/keyframes, JS-driven (rAF, Web Animations API, GSAP, Framer Motion), scroll-driven, canvas/WebGL — with element, trigger, properties, duration, easing.
+
+### 2. purpose-verification
+
+The hinge — apply the Purpose Test to each animation: does it COMMUNICATE state/causality, ORIENT the user, or CREATE meaning? Remove it mentally — if nothing is lost, it is PURPOSELESS.
+
+### 3. easing-system
+
+Easing as a vocabulary — enters decelerate (ease-out), exits accelerate (ease-in); count unique curves; are they named tokens or arbitrary per-component cubic-beziers?
+
+### 4. duration-consistency
+
+Durations on a systematic scale (tokens), each in its appropriate range — micro 80-150ms, entrances 200-400ms, exits faster than entrances; total entry choreography under 800ms.
+
+### 5. choreography
+
+Page entrances introduce themselves as a sequence following content hierarchy with consistent stagger; exits are swift and directional; state transitions communicate spatial relationships.
+
+### 6. scroll-animations
+
+No scroll hijacking, user controls pace, gentle parallax (10-30%), progress-linked not fire-and-forget, passive listeners, IntersectionObserver unobserved after firing.
+
+### 7. page-transitions
+
+Route changes animate with directional logic rather than hard-cut, shared-element continuity where possible, View Transitions API where supported, no long blank screens.
+
+### 8. micro-interactions
+
+Every interactive element responds to hover/focus/press with physical feedback (translate/scale, not color-only), consistent timing, popovers appear FROM their trigger.
+
+### 9. loading-skeleton
+
+Loading states are skeletons matching final layout (not bare spinners), shimmer is CSS-only, progressive reveal, smooth skeleton-to-content transition.
+
+### 10. webgl-canvas
+
+WebGL/P5 justified over CSS, 60fps desktop / 30fps mobile, tiered fallback (WebGL2/WebGL1/static), lazy-loaded, geometries/textures disposed on unmount, paused when off-screen.
+
+### 11. css-performance
+
+Animations use ONLY transform and opacity — animating width/height/margin/box-shadow triggers layout or paint; will-change used sparingly; no read-write-read forced reflow in loops.
+
+### 12. reduced-motion
+
+prefers-reduced-motion is a designed alternative not a nuclear kill-all — state changes still visible (modal still opens instantly), ambient motion pausable, interaction never blocked.
+
+### 13. mobile-motion
+
+Touch-specific :active feedback (not repurposed hover), gesture physics with momentum, safe-area respect, rAF paused when hidden, 30fps minimum under 4x CPU throttle.
+
+### 14. motion-meaning-gap
+
+The absence of motion is a finding — list added/removed, counter updates, tab switches, accordions, filtering, sorting that hard-cut where a transition should communicate the change.
+
+### 15. motion-excess
+
+Animations that harm — competing simultaneous motion, entrances over 600ms, distracting loops near text, redundant nested animations, gratuitous WebGL that could be CSS.
+
+## Falsification rules
+
+Every animation is guilty until proven purposeful. "It looks cool" is not a reason — FALSIFY each animation's justification: what does the user understand faster because of this motion? Every PASS must cite at least 3 concrete checks (the grepped property, the measured duration, the frame trace). Categorise findings as PURPOSE-vs-DECORATION, SYSTEM-vs-RANDOM, COMPOSITED-vs-EXPENSIVE, or PRESENT-vs-MISSING. A page with one perfectly timed animation beats a page with twelve good ones. Bias toward FAIL.
+
+## After the run
+
+The pipeline writes one structured verdict to:
+
+```
+Agentik_Runtime/audits.db    (history — `omega audit history motionaudit`)
+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": "motionaudit",
+    "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 motionaudit` 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 motion dimension is healthy. Insist on the score before you
+accept.
+
+## Reference
+
+Audit definition: `Agentik_SSOT/audits/motionaudit.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/perfaudit/SKILL.md

@@ -0,0 +1,161 @@
+---
+name: perfaudit
+description: Forensic performance audit — Is it FAST ENOUGH for humans to care — or does it bleed milliseconds nobody measured?. Runs the gather (deterministic) + falsify (agentic) pipeline, batches fixes, dispatches capped workers, re-audits, and persists scores. Use when the user says "/perfaudit", "audit performance", or asks to verify the performance health of the project.
+when_to_use: User says /perfaudit, audit performance, check performance, verify performance, is performance healthy.
+argument-hint: "[--scope <path>] [--fix] [--max-workers N]"
+arguments: [args]
+allowed-tools: Bash Read Edit Grep Glob Write
+---
+
+# perfaudit — forensic audit (Agentik OS Quality Arsenal)
+
+> Is it FAST ENOUGH for humans to care — or does it bleed milliseconds nobody measured?
+
+You are running the perfaudit 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 perfaudit $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. core-web-vitals
+
+Measure LCP (<2.5s), INP (<200ms), CLS (<0.1), TTFB (<800ms), FCP (<1.8s) on the hinge page; re-run throttled at 3G + 4x CPU and watch the score collapse.
+
+### 2. bundle-bloat
+
+Total initial JS compressed (<200KB target); barrel imports pulling whole libraries; duplicate deps at multiple versions; source maps shipped to prod.
+
+### 3. render-path
+
+Render-blocking CSS/scripts in the critical path; unnecessary React re-renders; layout thrashing (read-write-read); long tasks >50ms blocking interactivity.
+
+### 4. js-execution
+
+Parse cost per bundle; hydration time and mismatch errors; un-throttled scroll/resize handlers; async waterfalls that should be Promise.all.
+
+### 5. image-optimization
+
+PNG/JPEG where WebP/AVIF saves 60-80%; images larger than display size; missing width/height (CLS); missing lazy-loading below the fold; missing fetchpriority on the LCP image.
+
+### 6. font-loading
+
+WOFF2 used and subset to used glyphs; font-display:swap to prevent FOIT; critical fonts preloaded; layout shift when the web font swaps in.
+
+### 7. caching-strategy
+
+Cache-Control + immutable on fingerprinted assets; repeated identical API calls that should be memoized/SWR-cached; deploy invalidates stale CSS/JS hashes.
+
+### 8. ssr-ssg-strategy
+
+Each route uses the right rendering mode (SSR/SSG/ISR/CSR); static pages wrongly rendered per-request; SSR data fetching serial instead of parallel; streaming used for TTFB.
+
+### 9. code-splitting
+
+Route-based and component-based splitting working; vendor/framework chunks separated; heavy components (charts, editors, maps) lazy-loaded behind dynamic import.
+
+### 10. api-response-times
+
+Per-endpoint average <200ms and P95 <1s; over-fetching unused fields; sequential dependent calls on page load; missing pagination on list endpoints.
+
+### 11. n-plus-one
+
+Same query template fired in a loop with different params; ORM relationships lacking eager loading; SELECT * where columns suffice; total queries per page load >10.
+
+### 12. db-query-performance
+
+Queries >100ms; full table scans from missing indexes; joins/sorts without supporting indexes; large result sets without LIMIT; connection pool sized for concurrency.
+
+### 13. memory-leaks
+
+Heap growth over time; detached DOM nodes; event listeners/timers/intervals/sockets never cleaned on unmount; unbounded caches and history stacks.
+
+### 14. resource-hints-third-party
+
+LCP image and critical fonts preloaded; preconnect/dns-prefetch for third-party origins; render-blocking third-party scripts that could be deferred or facade-loaded.
+
+## Falsification rules
+
+Lighthouse scores lie — every green score must be re-verified throttled (3G + 4x CPU, cold cache) and twice to rule out a one-off blip. Categorise findings as SCORE-vs-REALITY, LAB-vs-FIELD, FIRST-vs-REPEAT, or AVERAGE-vs-P95. Every PASS cites ≥3 concrete measurements with actual numbers. "It's fast for me" (warm cache, fast machine) is not evidence. Bias toward FAIL — a 100 is earned, never assumed.
+
+## After the run
+
+The pipeline writes one structured verdict to:
+
+```
+Agentik_Runtime/audits.db    (history — `omega audit history perfaudit`)
+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": "perfaudit",
+    "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 perfaudit` 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 performance dimension is healthy. Insist on the score before you
+accept.
+
+## Reference
+
+Audit definition: `Agentik_SSOT/audits/perfaudit.yaml`
+Engine pipeline:  `omega_engine.audits.pipeline.AuditPipeline`
+Batcher:          `omega_engine.audits.batcher.batch_findings`
+History:          `omega_engine.audits.history`