Dodaios is an open-source agent OS for your desktop: it runs your coding agents, browser and apps by voice or chat, on your own machine. Formerly Personal Jarvis.
Python agent-orchestrationai-agentai-coding-assistantclaude-codecoding-agentcomputer-usedesktop-applocal-firstmcppersonal-jarvisvoice-assistantvoice-coding
ci: the gates the rules already promised now actually run
Harald1fcdbfbb6d33
diff --git a/.githooks/pre-commit b/.githooks/pre-commitindex 4648bbff59..9fc2736431 100755--- a/.githooks/pre-commit+++ b/.githooks/pre-commit@@ -64,6 +64,16 @@ if [ -f "$syncdir" ]; thenfifi+# --- .claude/agents/ -> .codex/agents/ projection ----------------------------+# The third tree. Not a twin but a generated projection (Markdown -> Codex TOML),+# so there is no both-sides-edited conflict to resolve: .claude/ always wins and+# a hand-edit in .codex/ is simply overwritten. Never blocks — worst case the+# projection is rewritten and staged under the commit that changed its source.+synccodex="scripts/ci/sync_codex_agents.py"+if [ -f "$synccodex" ]; then+ "$PY" "$synccodex" --stage --quiet </dev/null+fi+# --- LANGUAGE gate (FAIL-CLOSED on confirmed German) --------------------------# English-only artifacts (CLAUDE.md rule 1). Checks the STAGED changes so new# German is caught at COMMIT time — the real write path (incl. the auto-savediff --git a/.github/workflows/ci.yml b/.github/workflows/ci.ymlindex de43fac25b..8891d5f0f6 100644--- a/.github/workflows/ci.yml+++ b/.github/workflows/ci.yml@@ -297,6 +297,27 @@ jobs:-q -p no:cacheproviderpython scripts/skill_relevance_calibrate.py+ # The four guards CLAUDE.md §10 names by name, in their OWN blocking step+ # for the same reason the skill eval has one: the suite above ends in+ # `|| echo`, so a broken guard costs one passed test against a ~700-test+ # cushion above the min-passed floor and rides through green. These four+ # pin contracts that are cheap to break and expensive to notice later —+ # the router stays a pure dispatcher (ADR-0011), the voice scrubber stays+ # regex-only (AP-11), a status enum stays in step across all five layers+ # (AP-4, BUG-008 recurred 4x), and ONE resolver decides a turn's output+ # language (CLAUDE.md §1). Seconds to run; add a guard here when you add+ # one there.+ - name: Contract guards (BLOCKING — router, scrubber, enum parity, language)+ if: matrix.os == 'ubuntu-latest'+ shell: bash+ run: |+ python -m pytest \+ tests/unit/brain/test_routing.py \+ tests/unit/brain/test_output_filter.py \+ tests/unit/sessions/test_hangup_reason_parity.py \+ tests/unit/core/test_turn_language.py \+ -q -p no:cacheprovider+# jarvisctl control-CLI unit suite across the three supported desktops.# jarvisctl is a thin cross-platform HTTP client (paths via platformdirs,# UTF-8 I/O, no Windows APIs); this job proves it imports + its unit tests@@ -510,6 +531,18 @@ jobs:- name: Brand-logo gate (BLOCKING)run: python scripts/ci/check_brand_logos.py+ # CLAUDE.md §0 promises the agent-knowledge mirrors are held by "hook ++ # pre-commit + CI". The CI leg did not exist until 2026-08-20, so a commit+ # made with hooks uninstalled (`install_git_hooks.py` is a manual step)+ # could drift the trees with nothing to catch it. Three trees, two+ # engines: .claude <-> .agents is byte-identical, .codex is a generated+ # projection. Both are cheap — stdlib and git only.+ - name: Agent-knowledge mirrors (BLOCKING)+ run: |+ python scripts/ci/sync_agents_md.py --check+ python scripts/ci/sync_agents_dir.py --check+ python scripts/ci/sync_codex_agents.py --check+# Output Language Policy enforcement (CLAUDE.md, HIGHEST PRIORITY): block any# NEWLY ADDED German text from reaching GitHub. Diff-based, so the in-flight# DE->EN translation backlog (pre-existing German) does NOT turn this red - only@@ -673,10 +706,15 @@ jobs:run: npm run build# The entry chunk is parsed and executed before the UI paints a single- # pixel, so its size IS startup latency. Guarding it here is the frontend- # twin of the Python boot budget in .githooks/pre-push: both block the- # same regression class, where a statically imported view or library- # quietly adds seconds to every launch.+ # pixel, so its size IS startup latency. It guards the same regression+ # class as the Python boot budget — a statically imported view or library+ # quietly adding seconds to every launch — but it is the only HALF of that+ # pair a CI runner can measure. `check_boot_budget.py` boots the whole+ # application and needs an audio device to reach VOICE_USABLE, so it left+ # pre-push on 2026-08-05 and has no CI home; it is an on-demand local+ # command (`python scripts/ci/check_boot_budget.py`) that AP-26 asks you+ # to run by hand after touching the startup path. Do not read this step as+ # covering the Python side.- name: Check startup bundle budgetworking-directory: ${{ github.workspace }}run: python3 scripts/ci/check_frontend_bundle_budget.pydiff --git a/.github/workflows/macos-desktop.yml b/.github/workflows/macos-desktop.ymlindex fb0f2387e6..dbbcf96e2f 100644--- a/.github/workflows/macos-desktop.yml+++ b/.github/workflows/macos-desktop.yml@@ -6,7 +6,35 @@name: macOS desktop+# Trigger note (2026-08-20): this ran on `pull_request` only, and the project+# has no PR flow — 0 merge commits in the last 200 — so the macOS leg had not+# fired in months while CLOUD.md Rule #1 called macOS a first-class target "in+# the SAME change". A non-negotiable rule whose proof never runs is a rule on+# paper. The path filters below keep the cost honest: the expensive runners+# wake only for a change that can actually break the desktop.on:+ push:+ branches:+ - main+ paths:+ - ".github/workflows/macos-desktop.yml"+ - ".githooks/pre-push"+ - "install/**"+ - "jarvis/admin/**"+ - "jarvis/audio/**"+ - "jarvis/autostart/**"+ - "jarvis/cu/**"+ - "jarvis/platform/**"+ - "jarvis/setup/**"+ - "jarvis/trigger/**"+ - "jarvis/ui/**"+ - "jarvis/vision/**"+ - "pyproject.toml"+ - "scripts/ci/check_boot_budget.py"+ - "scripts/measure_boot.py"+ - "scripts/measure_desktop_boot.py"+ - "tests/**"+ - "uv.lock"pull_request:paths:- ".github/workflows/macos-desktop.yml"diff --git a/AGENTS.md b/AGENTS.mdindex 7c5b2e0424..082347d12d 100644--- a/AGENTS.md+++ b/AGENTS.md@@ -5,9 +5,12 @@ numbers, unabridged) is [`docs/agent-contract.md`](docs/agent-contract.md) —read it before deep work.## 0. Mirror rule (BINDING)-`CLAUDE.md` ≡ `AGENTS.md` (byte-identical); `.claude/{agents,commands,skills}/`-≡ `.agents/{...}`. Auto-synced by hook + pre-commit + CI. Write for EVERY-coding agent, never Claude Code alone.+THREE trees, one source: `CLAUDE.md` ≡ `AGENTS.md` (byte-identical);+`.claude/{agents,commands,skills}/` ≡ `.agents/{...}`; `.codex/agents/*.toml`+is a GENERATED projection of `.claude/agents/*.md` — never hand-edit it.+Auto-synced by hook + pre-commit + CI (`sync_agents_md.py`,+`sync_agents_dir.py`, `sync_codex_agents.py`, each with `--check`). Write for+EVERY coding agent, never Claude Code alone.## 1. Language (BINDING, HIGHEST PRIORITY)Every committed artifact is ENGLISH. German ONLY on the closed product surfacediff --git a/CLAUDE.md b/CLAUDE.mdindex 7c5b2e0424..082347d12d 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -5,9 +5,12 @@ numbers, unabridged) is [`docs/agent-contract.md`](docs/agent-contract.md) —read it before deep work.## 0. Mirror rule (BINDING)-`CLAUDE.md` ≡ `AGENTS.md` (byte-identical); `.claude/{agents,commands,skills}/`-≡ `.agents/{...}`. Auto-synced by hook + pre-commit + CI. Write for EVERY-coding agent, never Claude Code alone.+THREE trees, one source: `CLAUDE.md` ≡ `AGENTS.md` (byte-identical);+`.claude/{agents,commands,skills}/` ≡ `.agents/{...}`; `.codex/agents/*.toml`+is a GENERATED projection of `.claude/agents/*.md` — never hand-edit it.+Auto-synced by hook + pre-commit + CI (`sync_agents_md.py`,+`sync_agents_dir.py`, `sync_codex_agents.py`, each with `--check`). Write for+EVERY coding agent, never Claude Code alone.## 1. Language (BINDING, HIGHEST PRIORITY)Every committed artifact is ENGLISH. German ONLY on the closed product surfacediff --git a/CLOUD.md b/CLOUD.mdindex ebaa56e352..029bc7acb7 100644--- a/CLOUD.md+++ b/CLOUD.md@@ -43,7 +43,7 @@ Concretely, Rule #1 means:- (a) it lives behind a runtime capability check (not an `import` at module top level that crashes on the wrong OS), **and**- (b) it sits inside an optional extras group (`[desktop]`, `[local-stt]`, `[vision-local]`, …), **and**- (c) it degrades to a graceful, clearly-messaged no-op (in English) on the platforms where it is unavailable.-4. **No new hard dependency on an OS-bound package.** `pywin32`, `pywinauto`, `pyautogui`, `sounddevice`, `faster-whisper`, `onnxruntime-gpu`, `openwakeword`, `global-hotkeys`, `mss`, `pywebview` and friends go into an extras group — never the base install.+4. **No new dependency that can break the base install or the boot.** The test is behavioural, not a name list: `pip install` and `import jarvis` must succeed on a fresh `python:3.11-slim` with no GPU, no audio device, and no native OS API. Three mechanisms satisfy it, and a package may use whichever fits: an **extras group** (`[desktop]`, `[desktop-linux]`, `[desktop-macos]`, `[local-voice]`), an **environment marker** that keeps the wheel off the platforms it cannot serve, or a **lazy import behind a capability probe** so the module never loads where it would fail. `pywin32`, `pywinauto`, `pyautogui`, `faster-whisper`, `onnxruntime-gpu`, `global-hotkeys`, `mss` and `pywebview` are extras. `sounddevice`, `openwakeword`, `onnxruntime`, `vosk` and `aiortc` sit in the base install *by marker and lazy import* — they install cleanly, and the features that need them degrade honestly when the system library or device is absent. Gates: `check_import_clean.py` (module-scope platform imports), `check_requirements_sync.py` and `check_lockfile_universal.py` (torch-free, universal lock), `check_portable_install_matrix.py` (the install itself). Adding a package that fails any of those is the defect — the wording here follows the gates, not a frozen list of names.5. **Use cross-platform primitives by default:** `pathlib.Path` over hand-built `\`/`/` paths, `sys.platform` / capability probes over assuming Windows, `subprocess` flags guarded per-OS, UTF-8 everywhere (never assume cp1252), and config/data dirs resolved via a platform-aware helper rather than hardcoded `C:\Users\...`.6. **CI must prove it.** Cross-platform parity is verified, not assumed — the test matrix should exercise Linux, macOS, and Windows (at minimum: import + boot + base test suite on each).diff --git a/docs/PHILOSOPHY.md b/docs/PHILOSOPHY.mdindex dce7f31170..a6ac3f212d 100644--- a/docs/PHILOSOPHY.md+++ b/docs/PHILOSOPHY.md@@ -58,15 +58,33 @@ Concretely:This document declares the **target**, not the **current state**.-As of 2026-05-18 the codebase still hardcodes several local-hardware assumptions:--- `jarvis.toml` defaults STT to `faster-whisper` on `device='cuda'`.-- `pyproject.toml` lists `faster-whisper`, `openwakeword`, `pywin32`, `sounddevice`, `pywinauto`, `pyautogui`, `global-hotkeys` as **hard** runtime dependencies.-- `README.md` §1 ("Quick install & first-run") and `CLAUDE.md` §"Windows specifics" assume Windows 11 Pro with a tray, a headset, and an `asInvoker` UAC manifest.-- ADR-0001 (Named-Pipe HMAC), ADR-0010 (`MsgWaitForMultipleObjects`), ADR-0015 (Obsidian registry probing) bake in Windows APIs without declaring them optional.-- `scripts/preflight.ps1`, `run.bat`, `scripts/drift-guard-daemon.ps1`, `scripts/check-working-tree.ps1`, `scripts/auto-push-eod.ps1` are PowerShell-only.--**These are not bugs in this document.** They are the **remediation backlog**. This document is the **North Star**; future PRs steer toward it.+**Status of the original backlog (re-checked 2026-08-20).** The list below was+written on 2026-05-18. Most of it has since been paid off, and leaving the old+wording in place did active harm: a paragraph that is *wholly* stale stops being+read, and a real violation hiding inside it goes unnoticed. Current state:++- **Done** — `faster-whisper`, `pywin32`, `pywinauto`, `pyautogui`,+ `global-hotkeys`, `mss` and `pywebview` all left the base install. The base is+ torch-free and enforced (`check_requirements_sync.py`,+ `check_lockfile_universal.py`), the package imports clean on Linux and macOS+ (`check_import_clean.py`), and CI proves the install across the matrix+ (`check_portable_install_matrix.py`).+- **Done differently than planned** — `sounddevice`, `openwakeword`,+ `onnxruntime`, `vosk` and `aiortc` stayed in the base install but are gated by+ environment marker and lazy import instead of an extras group. That satisfies+ the doctrine's actual test (install and boot succeed on `python:3.11-slim`);+ `CLOUD.md` Rule #1 point 4 now names all three permitted mechanisms rather+ than a fixed list of package names.+- **Still open** — the maintainer's operational scripts remain PowerShell-only+ (`preflight.ps1`, `run.bat`, `drift-guard-daemon.ps1`,+ `check-working-tree.ps1`, `auto-push-eod.ps1`). That is deliberate and+ permitted: see §6. The ADRs named in the original list still describe+ Windows APIs without marking them optional; `docs/os-parity.md` is the live+ register of what actually degrades where.++**A stale backlog is a doc bug.** When you pay an item off, strike it here in+the same change — the value of this section is that a reader can trust it.+This document remains the **North Star**; future PRs steer toward it.**Pre-existing code is grandfathered until touched.** A code path that already violates the doctrine does not need to be rewritten in a panic. But any new change from 2026-05-18 forward is evaluated against this doctrine. Any *touch* of a violating code path is an opportunity to migrate it toward the cloud-first default, not extend the violation.diff --git a/docs/agent-contract.md b/docs/agent-contract.mdindex 65d4bf5627..dc4ede1590 100644--- a/docs/agent-contract.md+++ b/docs/agent-contract.md@@ -8,18 +8,31 @@ one. Section numbers here match the root file's section numbers.----## 0. Mirror rule — CLAUDE.md ≡ AGENTS.md, .claude/ ≡ .agents/ (BINDING)+## 0. Mirror rule — THREE trees, one source (BINDING)`CLAUDE.md` is canonical; `AGENTS.md` is its **byte-identical twin** for othertools. The same holds for the versioned agent-knowledge trees:`.claude/{agents,commands,skills}/` ↔ `.agents/{agents,commands,skills}/` —everything in them addresses **every** coding agent (Codex, Gemini CLI, ...),-never Claude Code alone; write it accordingly. Sync engines-`scripts/ci/sync_agents_md.py` / `sync_agents_dir.py` run as a live-`PostToolUse` hook, `.githooks/pre-commit --stage`, and a `--check` CI gate;-after editing either side, sync before committing. Deletions propagate.-Gitignored/private entries (e.g. `.claude/skills/security-github/`) stay out-of the mirror on both sides.+never Claude Code alone; write it accordingly.++A **third** tree exists: `.codex/agents/*.toml`, the same definitions in the+shape Codex reads. It is a **generated projection** of `.claude/agents/*.md`,+not a twin — front matter becomes `name` / `description`, the Markdown body+becomes `developer_instructions`, and Claude-Code-only fields (`tools`,+`model`, `must_read`) are dropped rather than invented. **Never hand-edit a+`.toml` there**; the next run overwrites it. This tree went unnamed in this+contract and unsynced by any engine until 2026-08-20, and drifted the whole+time — its `code-reviewer` still demanded a `SUB_TOOLS` set that AP-14 forbids+while its Markdown source had moved on. A mirror nothing verifies is not a+mirror.++Sync engines `scripts/ci/sync_agents_md.py`, `sync_agents_dir.py` and+`sync_codex_agents.py` run as a live `PostToolUse` hook,+`.githooks/pre-commit --stage`, and a `--check` CI gate (the `repo-hygiene`+job). After editing the canonical side, sync before committing. Deletions+propagate. Gitignored/private entries (e.g. `.claude/skills/security-github/`)+stay out of the mirror on every side.---diff --git a/scripts/ci/sync_codex_agents.py b/scripts/ci/sync_codex_agents.pyindex 163073aa4a..ba4ddd846e 100644--- a/scripts/ci/sync_codex_agents.py+++ b/scripts/ci/sync_codex_agents.py@@ -32,11 +32,13 @@ Usage::python scripts/ci/sync_codex_agents.py # write the projectionpython scripts/ci/sync_codex_agents.py --check # fail if it is stale+ python scripts/ci/sync_codex_agents.py --stage # write, then `git add` it"""from __future__ import annotationsimport argparse+import subprocessimport sysfrom pathlib import Path@@ -118,7 +120,32 @@ def render_toml(name: str, description: str, body: str) -> str:)-def project(check_only: bool) -> int:+def git_add(paths: list[Path]) -> None:+ """Stage exactly the files this script touched.++ Scoped to explicit paths on purpose: the working tree is frequently shared+ with other agent sessions, and a broad ``git add`` sweeps their in-flight+ work into someone else's commit (CLAUDE.md §9).+ """+ if not paths:+ return+ try:+ subprocess.run(+ ["git", "add", "--", *(str(p) for p in paths)],+ cwd=REPO_ROOT,+ check=False,+ capture_output=True,+ )+ except OSError:+ pass # no git on PATH: the projection is still written, just not staged+++def project(check_only: bool, stage: bool = False, quiet: bool = False) -> int:+ def say(message: str) -> None:+ """Progress output. ``--quiet`` silences it; errors never route here."""+ if not quiet:+ print(message)+if not SOURCE_DIR.is_dir():print(f"sync_codex_agents: {SOURCE_DIR} does not exist", file=sys.stderr)return 1@@ -129,9 +156,7 @@ def project(check_only: bool) -> int:for source in sorted(SOURCE_DIR.glob("*.md")):if source.stem in SKIP_STEMS:continue- fields, body = split_front_matter(- source.read_text(encoding="utf-8"), source- )+ fields, body = split_front_matter(source.read_text(encoding="utf-8"), source)target = TARGET_DIR / f"{source.stem}.toml"expected[target] = render_toml(fields["name"], fields["description"], body)@@ -166,15 +191,21 @@ def project(check_only: bool) -> int:file=sys.stderr,)return 1- print(f"sync_codex_agents: {len(expected)} agents in sync.")+ say(f"sync_codex_agents: {len(expected)} agents in sync.")return 0for name in stale:- print(f"sync_codex_agents: rewrote .codex/agents/{name}")+ say(f"sync_codex_agents: rewrote .codex/agents/{name}")for name in orphaned:- print(f"sync_codex_agents: removed .codex/agents/{name}")+ say(f"sync_codex_agents: removed .codex/agents/{name}")if not stale and not orphaned:- print(f"sync_codex_agents: {len(expected)} agents already in sync.")+ say(f"sync_codex_agents: {len(expected)} agents already in sync.")++ if stage:+ touched = [TARGET_DIR / n for n in stale]+ touched += [TARGET_DIR / n for n in orphaned]+ git_add(touched)+return 0@@ -185,9 +216,19 @@ def main() -> int:action="store_true",help="report drift and exit non-zero instead of rewriting",)+ parser.add_argument(+ "--stage",+ action="store_true",+ help="git add the files this run rewrote or removed (for pre-commit)",+ )+ parser.add_argument(+ "--quiet",+ action="store_true",+ help="suppress the per-file lines (errors still print)",+ )args = parser.parse_args()try:- return project(check_only=args.check)+ return project(check_only=args.check, stage=args.stage, quiet=args.quiet)except FrontMatterError as exc:print(f"sync_codex_agents: {exc}", file=sys.stderr)return 1