Skip to content

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.

ci: the gates the rules already promised now actually run

Harald1fcdbfbb6d33
diff --git a/.githooks/pre-commit b/.githooks/pre-commit
index 4648bbff59..9fc2736431 100755
--- a/.githooks/pre-commit
+++ b/.githooks/pre-commit
@@ -64,6 +64,16 @@ if [ -f "$syncdir" ]; then
fi
fi
+# --- .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-save
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index de43fac25b..8891d5f0f6 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -297,6 +297,27 @@ jobs:
-q -p no:cacheprovider
python 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 budget
working-directory: ${{ github.workspace }}
run: python3 scripts/ci/check_frontend_bundle_budget.py
diff --git a/.github/workflows/macos-desktop.yml b/.github/workflows/macos-desktop.yml
index 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.md
index 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 surface
diff --git a/CLAUDE.md b/CLAUDE.md
index 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 surface
diff --git a/CLOUD.md b/CLOUD.md
index 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.md
index 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.md
index 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 other
tools. 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.py
index 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 projection
python 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 annotations
import argparse
+import subprocess
import sys
from 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 0
for 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