@agentikos/omega-os 0.1.0

package/omega/Agentik_Extra/etc/structure.yaml

@@ -0,0 +1,46 @@
+# Omega OS — arborescence manifest.
+# A scheduled check (automation-educator) compares the live tree to this file
+# every hour and reports drift. This is the contract for the 8-block rack.
+
+version: 1
+master: ~/Omega
+
+blocks:
+  Agentik_SSOT:
+    nature: truth
+    git: true
+    children: [rules, skills, commands, audits, schemas, mcp, prompts]
+  Agentik_Engine:
+    nature: engine
+    git: true
+    children: [omega_engine, tests]
+  Agentik_Orchestration:
+    nature: definitions
+    git: true
+    children: [topologies, roles, verifier, router, educators, autonomous, hooks, automations]
+  Agentik_Providers:
+    nature: wiring
+    git: true
+    children: [claude, glm, openai, _template]
+  Agentik_Coding:
+    nature: projects
+    git: per-project
+    children: [projects, worktrees]
+  Agentik_Tools:
+    nature: external
+    git: false
+    children: [bin, knowledge]
+  Agentik_Runtime:
+    nature: live-state
+    git: false
+    children: [eventlog, sessions, verdicts, snapshots, memory, locks]
+  Agentik_Extra:
+    nature: ephemeral
+    git: false
+    children: [var, staging, etc]
+
+rules:
+  - master folder holds exactly 8 entries, all prefixed Agentik_
+  - no spaces in any path
+  - secrets live only in Agentik_Extra/etc/secrets (chmod 700, encrypted)
+  - nothing is written outside ~/Omega

package/omega/Agentik_Orchestration/README.md

@@ -0,0 +1,43 @@
+# Agentik_Orchestration — the definitions
+
+> **Nature:** your business definitions · **Lifecycle:** often changes · **Git:** dedicated repo
+
+This block holds the **logic**, not the runtime. The engine
+(`Agentik_Engine/`) is generic — it executes graphs of `Task`s and knows nothing
+about "oracles". *This* block declares what an oracle is, which topology runs,
+how the verifier scores, which model serves which role, and which autonomous
+agents exist. You can redesign all of it without touching the engine.
+
+## Contents
+
+| Folder | What |
+|---|---|
+| `topologies/` | orchestration graphs — `aisb-oracle-worker.yaml` is one; the engine runs any graph |
+| `roles/` | role definitions — what an `aisb` / `oracle` / `manager` / `worker` / `verifier` does |
+| `verifier/` | the audit gate — `audit-router.yaml` selects audits per task type + the score threshold |
+| `router/` | the model router — maps a task to a required *capability*, then to a provider |
+| `educators/` | the 8 educators — the self-improving layer (see `educators/README.md`) |
+| `autonomous/` | autonomous-agent charters (see `autonomous/README.md`) |
+| `hooks/` | event-driven hooks — react to event-bus patterns |
+| `automations/` | scheduled routines — a cold backstop; the live path is the bus |
+
+## How a mission flows
+
+1. A message arrives (Telegram / CLI). **AISB** (persistent root dispatcher)
+   classifies it and routes it to a project **Oracle**.
+2. The **Oracle** plans — it produces a task DAG for a topology in `topologies/`.
+3. The **Manager** schedules the DAG: it spawns **Workers**, in parallel where
+   their file scopes are disjoint.
+4. Each Worker reaches `CLAIMED_DONE` → a **Verifier** runs the audit gate
+   (`verifier/audit-router.yaml`) → `VERIFIED` or `REJECTED`.
+5. When every child is terminal the join barrier emits `scope.joinable`; the
+   Oracle quality-gates and reports up to AISB; AISB reports to the channel.
+
+The engine guarantees steps 4–5 mechanically — see
+[`../../../docs/ENGINE-SPEC.md`](../../../docs/ENGINE-SPEC.md).
+
+## Topology is data
+
+`aisb-oracle-worker` is *one* graph. A pipeline, a fan-out mesh, a five-level
+hierarchy — each is another file in `topologies/`. A new orchestration needs a
+new graph, **never new engine code**.

package/omega/Agentik_Orchestration/autonomous/README.md

@@ -0,0 +1,29 @@
+# Autonomous Agents
+
+> Long-running, channel-bound, self-directed agents — as first-class nodes of
+> the one engine. Not a separate subsystem.
+
+An autonomous agent is a `Task`/`Node` with `lifecycle: persistent` and a
+`trigger`. Same reducer, same join barrier, same audit gate, same MCP and
+skills as any mission task. It inherits verified completion and the deadman for
+free.
+
+When its trigger fires, an autonomous agent opens a scope and spawns ephemeral
+missions (the normal `aisb-oracle-worker` topology) inside it — then reports to
+its bound Telegram channel and waits for the next trigger.
+
+## Files
+
+- `example-agents.yaml` — a charter template plus two worked examples.
+- one `<agent-id>.yaml` charter per agent you register.
+
+## Register an agent
+
+1. Add a charter file here (copy the template in `example-agents.yaml`).
+2. List its id under `autonomous_agents:` in the install manifest, or run the
+   installer's autonomous step.
+3. The autonomous-agent supervisor (`systemd` service) loads it and keeps its
+   persistent node alive.
+
+Full design — triggers, charter fields, the persistent-vs-ephemeral deadman
+behaviour: [`../../../docs/AUTONOMOUS-AGENTS.md`](../../../docs/AUTONOMOUS-AGENTS.md).

package/omega/Agentik_Orchestration/autonomous/example-agents.yaml

@@ -0,0 +1,85 @@
+# Autonomous-agent charters — template + two worked examples.
+# One agent per file in production; this file groups examples for reference.
+
+# ─────────────────────────────────────────────────────────────────────────────
+# TEMPLATE — copy this block into <agent-id>.yaml and fill it in.
+# ─────────────────────────────────────────────────────────────────────────────
+template:
+  id: <agent-id>
+  role: <role-name>
+  lifecycle: persistent
+  charter: >
+    A clear, plain-language statement of what this agent holds responsibility
+    for, and the boundary of its judgement.
+  trigger:
+    type: <cron|event|webhook|channel>
+    config: {}
+  channel:
+    telegram_topic: <topic-id>      # where it listens AND reports
+  budget:
+    max_iterations: 5
+    heartbeat_interval_s: 300
+  provider: <provider-id>           # e.g. glm for triage; missions escalate
+  allowed:
+    skills: []
+    mcp: []
+    topologies: [aisb-oracle-worker]
+  guardrails:
+    may_spawn_missions: true
+    may_ship: false
+
+# ─────────────────────────────────────────────────────────────────────────────
+# EXAMPLE 1 — a support agent bound to a support channel.
+# ─────────────────────────────────────────────────────────────────────────────
+support-agent:
+  id: support-agent
+  role: customer-support
+  lifecycle: persistent
+  charter: >
+    Watch the support channel. Triage every inbound message, draft a reply, and
+    for anything that needs a code change open a mission against the relevant
+    project. Never close a thread the customer has not confirmed.
+  trigger:
+    type: channel
+    config: { telegram_topic: 4012 }
+  channel:
+    telegram_topic: 4012
+  budget:
+    max_iterations: 5
+    heartbeat_interval_s: 300
+  provider: glm
+  allowed:
+    skills: [classify-intent, draft-reply, rag-route]
+    mcp: [filesystem, github, linear]
+    topologies: [aisb-oracle-worker]
+  guardrails:
+    may_spawn_missions: true
+    may_ship: false
+
+# ─────────────────────────────────────────────────────────────────────────────
+# EXAMPLE 2 — a growth agent on a daily schedule.
+# ─────────────────────────────────────────────────────────────────────────────
+growth-agent:
+  id: growth-agent
+  role: growth
+  lifecycle: persistent
+  charter: >
+    Every morning, pull yesterday's product metrics, find the single biggest
+    regression or opportunity, and open one scoped mission to act on it.
+    One mission per day — never a backlog.
+  trigger:
+    type: cron
+    config: { schedule: "0 7 * * *" }
+  channel:
+    telegram_topic: 4020
+  budget:
+    max_iterations: 3
+    heartbeat_interval_s: 600
+  provider: claude
+  allowed:
+    skills: [rag-route, metrics-read, prioritize]
+    mcp: [filesystem, postgres, github]
+    topologies: [aisb-oracle-worker]
+  guardrails:
+    may_spawn_missions: true
+    may_ship: false

package/omega/Agentik_Orchestration/educators/README.md

@@ -0,0 +1,55 @@
+# The Educators — the self-improving layer
+
+> Eight generators/compilers. Each takes a high-level intention and produces the
+> correct artifact **into the SSOT**, under the quality gate. They are the
+> factory floor of Omega OS.
+
+An educator is itself an agent (a provider call) plus typed code that validates
+and installs the result. The SSOT is the system's genome; the educators are how
+that genome evolves.
+
+## The eight
+
+| Educator | Generates & maintains |
+|---|---|
+| `prompt-educator` | the prompts passed between levels (AISB ↔ Oracle ↔ Manager ↔ Worker) |
+| `artifact-educator` | templates for deliverables — reports, docs, components |
+| `skill-educator` | new skills, and the upkeep of the SSOT skill catalog |
+| `coworker-educator` | worker / agent role definitions |
+| `connection-educator` | connector configs — MCP servers, APIs, provider endpoints |
+| `automation-educator` | crons, hooks, reactors |
+| `claudecode-educator` | watches the Claude Code changelog and updates the SSOT + adapters |
+| `loop-educator` | goal-loop and verification patterns |
+
+> `claudecode-educator` is critical: when the platform ships a new primitive
+> (the `/goal` episode in the Omega whitepaper is the cautionary tale), this
+> educator detects it and updates the SSOT — the system keeps pace by itself.
+
+## The promotion pipeline — never silent self-modification
+
+An educator does **not** write straight to the SSOT. It writes to staging:
+
+```
+educator generates artifact
+        │
+        ▼
+Agentik_Extra/staging/promotion/      (proposed change, diffable)
+        │
+        ▼
+audit gate  (the Quality Arsenal — same verifier as for code)
+        │
+        ├─ score ≥ threshold  ──▶ promoted into Agentik_SSOT/   (+ a commit)
+        └─ score < threshold  ──▶ rejected, findings logged
+```
+
+Above a configurable confidence score, promotion is autonomous; below it, a
+human approves via a Telegram button. Every promotion is a git diff and is
+reversible. The system improves itself — never blindly.
+
+## The feedback loop
+
+The learning loop (`SMITH`) reads mission outcomes — success, rework, cost,
+time — and tells each educator what to fix: "the prompt template X causes
+rework", "a skill Y is missing". That is the auto-improvement cycle.
+
+> Each educator is scaffolded as a skill spec to be built out. Status: spec.

package/omega/Agentik_Orchestration/topologies/aisb-oracle-worker.yaml

@@ -0,0 +1,42 @@
+# Topology: aisb-oracle-worker
+#
+# The classic Omega mission graph. The engine executes ANY graph of this shape;
+# this file is DATA, not code. A new orchestration is a new file here.
+
+id: aisb-oracle-worker
+description: Intake -> plan -> execute -> verify, with verified completion.
+
+nodes:
+  - id: aisb
+    kind: dispatcher
+    role: aisb
+    lifecycle: persistent      # AISB is the always-on root scope
+  - id: oracle
+    kind: dispatcher
+    role: oracle
+    parent: aisb
+  - id: manager
+    kind: dispatcher
+    role: manager
+    parent: oracle
+  - id: worker
+    kind: executor
+    role: worker
+    parent: manager
+  - id: verifier
+    kind: verifier
+    role: audit
+    parent: manager            # the gate between a worker's CLAIMED_DONE and VERIFIED
+
+edges:
+  - { from: aisb,    to: oracle }    # AISB routes a mission to a project oracle
+  - { from: oracle,  to: manager }   # the oracle plans; the manager coordinates
+  - { from: manager, to: worker }    # the manager spawns workers
+  - { from: worker,  to: verifier }  # every CLAIMED_DONE goes through the gate
+
+policy:
+  on_partial: retry_failed           # retry_failed | accept_partial | fail_up
+  parallelism: scope_disjoint        # workers run in parallel only if file scopes disjoint
+  worker_budget:
+    max_iterations: 3
+    heartbeat_interval_s: 180

package/omega/Agentik_Orchestration/verifier/audit-router.yaml

@@ -0,0 +1,26 @@
+# Audit router — which audits run for which task. The verifier reads this to
+# assemble the audit gate (the CLAIMED_DONE -> VERIFIED transition).
+
+version: 1
+
+threshold:
+  default: 85        # aggregate score (out of 100) required to reach VERIFIED
+
+routes:
+  - match: { changed: ["*.py", "*.ts", "*.tsx", "*.js"] }
+    audits: [lint, types, code-review, runtime-flow]
+  - match: { changed: ["*.css", "*.scss", "ui/**"] }
+    audits: [code-review, visual-regression, runtime-flow]
+  - match: { task_role: worker }          # default for any worker
+    audits: [code-review, runtime-flow]
+  - match: { task_role: oracle }          # a dispatcher's "audit" is its barrier
+    audits: [scope-integrity]
+
+# runtime-flow is MANDATORY on any code-producing task. It starts the real
+# system, hits the endpoints, drives the UI path. No runtime-flow pass => no
+# VERIFIED. This is validate-live — Layer 5 of the safety mesh, and the single
+# mechanism that kills the lying "it's done".
+mandatory: [runtime-flow]
+
+# Retry is bounded by the task Budget: REJECTED -> dispatched, up to
+# max_iterations, then an honest FAILED with the findings as evidence.

package/omega/Agentik_Providers/README.md

@@ -0,0 +1,62 @@
+# Agentik_Providers — LLM wiring
+
+> **Nature:** the LLM wiring · **Lifecycle:** per-provider · **Git:** versioned (except secrets)
+
+Open this block over SSH and you see *all* the LLM wiring — and nothing else.
+One sub-folder per provider, zero business logic.
+
+## The contract
+
+Every LLM sits behind one interface. The engine talks only to this contract — it
+never knows whether Claude, GLM or OpenAI is behind it.
+
+```python
+class AgentProvider(Protocol):
+    id: str                                  # "claude" | "glm" | "openai"
+    def capabilities(self) -> ProviderCapabilities: ...
+    def run(self, req: AgentRequest) -> Iterator[AgentEvent]: ...
+    def cost(self, usage: Usage) -> float: ...
+```
+
+`AgentEvent` is one normalized stream: `thinking | text | tool_use |
+tool_result | done | error`. Each adapter does exactly one job — translate its
+provider's native API into that stream. ~200–400 lines per adapter.
+
+## Per-provider folders
+
+| Folder | Contents |
+|---|---|
+| `claude/` | adapter spec + `config/` — wraps the Claude Agent SDK (the reference adapter) |
+| `glm/` | adapter spec + `config/` — wraps the Zhipu GLM API |
+| `openai/` | adapter spec + `config/` — wraps the OpenAI Agents SDK / Responses API |
+| `_template/` | the skeleton — a new provider in ~5 minutes |
+| `registry.yaml` | active providers, capabilities, concurrency limits, role defaults |
+
+## Per-role assignment
+
+Because everything goes through one contract, a provider is assigned **per role**
+in `registry.yaml` — a cheap model for triage (AISB), Claude for code (Worker),
+a *different* model for audit (a genuine Popper falsification: the model that
+graded the code is not the model that wrote it).
+
+## Claude Max account pool
+
+The `claude/` provider supports **multiple Claude Code Max accounts**. Because
+Omega OS runs one engine (no tmux fan-out), accounts are not switched globally —
+the adapter holds a pool (`claude/accounts.yaml`) and distributes agent calls
+across accounts, so N Max accounts yield the sum of their rate limits as
+throughput. Manage it with `omega account` and `omega billing`. OAuth tokens
+live in the vault, never here. Full detail:
+[`../../../docs/ACCOUNT-AND-BILLING.md`](../../../docs/ACCOUNT-AND-BILLING.md).
+
+## Adding a provider
+
+1. Copy `_template/` to `<new-provider>/`.
+2. Implement the adapter against `AgentProvider` (translate native API → `AgentEvent`).
+3. Add an entry to `registry.yaml`.
+
+Zero changes to the engine. Zero changes to the SSOT.
+
+> Adapter implementations are build-out; `_template/` and this contract are the
+> spec. The model router (`Agentik_Engine/omega_engine/router.py`) resolves a
+> task to a provider using `registry.yaml`.

package/omega/Agentik_Providers/claude/accounts.example.yaml

@@ -0,0 +1,28 @@
+# Claude Code Max — account pool.
+#
+# Omega OS runs ONE engine, not N tmux sessions. An account is therefore not
+# "switched" globally — the Claude provider holds this pool and assigns each
+# agent call to an account, so N Max accounts give you the SUM of their rate
+# limits as usable throughput.
+#
+# OAuth tokens are NEVER stored here — only a reference into the encrypted vault
+# (Agentik_Extra/etc/secrets/). Add an account with `omega account login`.
+#
+# Copy to accounts.yaml and edit. See docs/ACCOUNT-AND-BILLING.md.
+
+version: 1
+
+selection: least-used          # round-robin | least-used | by-quota
+
+pool:
+  - id: max-primary
+    label: "Primary Max account"
+    secret_ref: CLAUDE_OAUTH_max-primary
+    weight: 1
+    status: active             # active | resting | disabled
+
+  - id: max-secondary
+    label: "Secondary Max account"
+    secret_ref: CLAUDE_OAUTH_max-secondary
+    weight: 1
+    status: active

package/omega/Agentik_Providers/registry.yaml

@@ -0,0 +1,30 @@
+# Active LLM providers — the model router reads this file.
+# Credentials are NOT here; they live in the secrets vault.
+
+version: 1
+
+providers:
+  - id: claude
+    adapter: claude
+    capabilities: [tool_use, streaming, mcp, long_context, vision]
+    limits: { max_concurrency: 8 }
+
+  - id: glm
+    adapter: glm
+    capabilities: [tool_use, streaming]
+    limits: { max_concurrency: 4 }
+
+  - id: openai
+    adapter: openai
+    capabilities: [tool_use, streaming, mcp, vision]
+    limits: { max_concurrency: 6 }
+
+# Default provider per role. The router reasons in required CAPABILITIES first,
+# then picks a provider that has them — so it can fail over if one is saturated.
+default_role_provider:
+  aisb:     glm        # triage — fast and cheap is enough
+  oracle:   claude     # planning — best reasoning
+  manager:  claude
+  worker:   claude     # writing code — Claude
+  verifier: claude
+  audit:    openai     # a different model than the worker — real falsification

package/omega/Agentik_Runtime/README.md

@@ -0,0 +1,30 @@
+# Agentik_Runtime — the live state
+
+> **Nature:** what is running now · **Lifecycle:** disposable except `memory/` · **Git:** not versioned
+
+This block is the runtime truth. Everything here is created and written while
+Omega OS runs.
+
+```
+Agentik_Runtime/
+├── eventlog/     omega.db — the append-only EVENT LOG, the source of runtime truth
+├── sessions/     one folder per live session (oracle / worker / autonomous agent)
+├── verdicts/     audit-gate verdicts (claimed_done → verified / rejected)
+├── snapshots/    periodic state snapshots — so reduce_task need not replay from genesis
+├── memory/       memory.db — the DURABLE store (the only thing here worth backing up)
+└── locks/        flocks and semaphores (GLM concurrency, build, audit)
+```
+
+## What to back up
+
+Almost nothing. `eventlog/`, `sessions/`, `verdicts/`, `snapshots/` and `locks/`
+are **disposable** — a fresh deployment regenerates them. The single exception is
+`memory/memory.db` (the durable, cross-mission memory and the hybrid-RAG FTS5
+base). Back that up; let everything else go.
+
+## The event log is the truth
+
+`eventlog/omega.db` is append-only. The state of any task is
+`reduce_task(events_for(task_id))`. Delete the event log and you have deleted the
+system's memory of every mission — but you have corrupted nothing, because there
+is no mutable state to corrupt.

package/omega/Agentik_SSOT/README.md

@@ -0,0 +1,36 @@
+# Agentik_SSOT — the Single Source of Truth
+
+> **Nature:** the neutral truth · **Lifecycle:** stable, promoted · **Git:** dedicated repo, read-only in prod
+
+This block is the genome of Omega OS. Everything that defines *how* the system
+behaves — rules, skills, commands, audit definitions, schemas, the MCP catalog,
+prompts — is written here **once**, in a provider-neutral form.
+
+No provider folder duplicates the SSOT. Each provider's adapter *compiles* this
+block into that provider's native shape (`omega sync`). A new LLM tomorrow =
+one new adapter; the SSOT is reused as-is.
+
+## Contents
+
+| Folder | What |
+|---|---|
+| `rules/` | the constitution and coding/security/ship rules — common to every agent |
+| `skills/` | canonical skill definitions |
+| `commands/` | canonical command definitions |
+| `audits/` | the audit definitions used by the verifier (the Quality Arsenal) |
+| `schemas/` | the JSON contracts — `event`, `task` (and more) |
+| `mcp/` | the MCP catalog + the canonical, neutral MCP config |
+| `prompts/` | prompt templates, generated by the prompt-educator |
+| `VERSION` | the SSOT version number |
+
+## Who writes here
+
+The SSOT is **read-only in production**. It is changed only by:
+
+1. **Humans**, via the git repo and a pull request.
+2. **The educators** (`Agentik_Orchestration/educators/`), which generate
+   artifacts into `Agentik_Extra/staging/promotion/` first; the audit gate
+   validates; only then is the change promoted into the SSOT.
+
+Either way, every change is a diff and is reversible. The system can evolve
+itself — never silently.

package/omega/Agentik_SSOT/VERSION

@@ -0,0 +1 @@
+0.1.0

package/omega/Agentik_SSOT/audits/a11yaudit.yaml

@@ -0,0 +1,69 @@
+# a11yaudit — OmegaOS Quality Arsenal definition.
+# Compact + structured: the Gestalt-Popper shell lives in omega_engine.audit_arsenal;
+# this file supplies only the domain — gather tools, phases, falsification rules.
+
+id: a11yaudit
+domain: accessibility
+question: "Can EVERYONE use it — keyboard-only, screen reader, low vision, reduced motion?"
+weight: 1.0
+threshold: 85
+
+applies_to:
+  roles: [worker]
+  changed: ["*.tsx", "*.jsx", "*.vue", "*.svelte", "*.html", "*.css", "*.scss"]
+
+# GATHER — deterministic a11y scanners, run first, no LLM.
+# These need a live URL; {path} is the target URL when one is provided.
+gather:
+  - name: axe-core
+    cmd: "npx --no-install @axe-core/cli {path} --exit 0 --save /dev/stdout || true"
+    when: "*"
+  - name: pa11y
+    cmd: "npx --no-install pa11y --reporter json --standard WCAG2AA {path} || true"
+    when: "*"
+  - name: lighthouse-a11y
+    cmd: "npx --no-install lighthouse {path} --only-categories=accessibility --output=json --quiet --chrome-flags='--headless --no-sandbox' || true"
+    when: "*"
+
+# PHASES — the agentic falsification pass investigates each.
+phases:
+  - id: hinge-keyboard-navigation
+    checks: "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."
+  - id: keyboard-traps-focus-visibility
+    checks: "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."
+  - id: wcag-aa-compliance
+    checks: "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."
+  - id: screen-reader-semantics
+    checks: "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."
+  - id: aria-correctness
+    checks: "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."
+  - id: semantic-elements
+    checks: "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."
+  - id: color-contrast
+    checks: "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."
+  - id: color-independence
+    checks: "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."
+  - id: form-labels-and-instructions
+    checks: "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."
+  - id: error-announcements
+    checks: "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."
+  - id: alt-text
+    checks: "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."
+  - id: heading-hierarchy-skip-nav
+    checks: "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."
+  - id: focus-management
+    checks: "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>."
+  - id: motion-and-touch-targets
+    checks: "@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: >
+  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.
+
+fix_loop: true