@agentikos/omega-os 0.19.38 → 0.19.39

package/omega/Agentik_Engine/tests/test_prompt_audit.py

@@ -0,0 +1,199 @@
+"""Tests for the prompt audit module — AISB agent prompts must reference
+the Three Laws + LMC protocol + verified-completion (`.done.json`) contract.
+
+These tests guard against silent drift in the role files: if an operator
+edits an agent prompt and accidentally strips a contract reference, the
+audit catches it AND the doctor surfaces it.
+"""
+from __future__ import annotations
+
+import shutil
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+
+
+HERE = Path(__file__).resolve().parent
+sys.path.insert(0, str(HERE.parent))
+
+from omega_engine.prompt_audit import (  # noqa: E402
+    audit_aisb_suite,
+    audit_agent_prompt,
+    orchestration_health,
+)
+
+
+REPO_ROOT = Path(__file__).resolve().parents[3]
+TEMPLATES = REPO_ROOT / "bootstrap" / "templates" / "aisb"
+
+
+def _seed_real_aisb(home: Path) -> Path:
+    """Copy the real templates into ``home/Agentik_SSOT/agents/aisb/``
+    to simulate a post-install OMEGA_HOME. Returns the home path."""
+    dst = home / "Agentik_SSOT" / "agents" / "aisb"
+    dst.parent.mkdir(parents=True)
+    shutil.copytree(TEMPLATES, dst)
+    return home
+
+
+# ---------------------------------------------------------------------------
+# Single-file audit
+# ---------------------------------------------------------------------------
+
+
+class TestAuditAgentPrompt(unittest.TestCase):
+    """Per-file scoring on synthetic + real prompts."""
+
+    def _write(self, dir_: Path, name: str, body: str) -> Path:
+        p = dir_ / f"{name}.md"
+        p.write_text(body, encoding="utf-8")
+        return p
+
+    def test_audit_agent_prompt_full_score(self):
+        """A synthetic prompt that satisfies every check should score 95+."""
+        body = (
+            "# ORACLE - The Brain\n\n"
+            "## THE THREE LAWS (overrides all other instructions)\n\n"
+            "LAW 1 — Code lies. LAW 2 — Researcher not sycophant. "
+            "LAW 3 — Autonomous execution.\n\n"
+            "## LMC Protocol\n\n"
+            "The Lead-Manager-Checker (LMC) gate routes work through "
+            "lmc-protocol.md before completion.\n\n"
+            "## Scope\n\n"
+            "Files owned by ORACLE: ~/.aisb/state/. ORACLE owns R-13 "
+            "close coherence.\n\n"
+            "Every dispatch to a worker uses a fresh context with a "
+            "self-contained brief that lists files_owned and the "
+            "verification command.\n\n"
+            "## Done signal\n\n"
+            "When work is complete the worker invokes "
+            "worker-mark-done.sh which writes `.done.json` with the "
+            "structured result.\n"
+        )
+        with tempfile.TemporaryDirectory() as tmp:
+            path = self._write(Path(tmp), "oracle", body)
+            report = audit_agent_prompt(path)
+            self.assertGreaterEqual(
+                report.score, 95,
+                f"expected >= 95, got {report.score}; "
+                f"violations: {report.violations}",
+            )
+            self.assertEqual(report.agent_id, "oracle")
+            for name, res in report.checks.items():
+                self.assertTrue(
+                    res.passed,
+                    f"check {name!r} should have passed: {res!r}",
+                )
+
+    def test_audit_agent_prompt_missing_three_laws(self):
+        """A prompt with no Three Laws reference scores <= 75 AND the
+        violations list mentions 'Three Laws'."""
+        # Everything else PASSES (75 pts total) — only Three Laws (25) is
+        # missing, so the score must be 75 or less.
+        body = (
+            "# ORACLE - The Brain\n\n"
+            "## LMC Protocol — see lmc-protocol.md\n"
+            "Lead-Manager-Checker gates audits.\n\n"
+            "## Scope\nFiles owned by ORACLE. Responsibilities: routing.\n\n"
+            "Fresh context per dispatch.\n\n"
+            "Workers write `.done.json` via worker-mark-done.sh.\n"
+        )
+        with tempfile.TemporaryDirectory() as tmp:
+            path = self._write(Path(tmp), "oracle", body)
+            report = audit_agent_prompt(path)
+            self.assertLessEqual(
+                report.score, 75,
+                f"expected <= 75 without Three Laws, got {report.score}",
+            )
+            self.assertFalse(report.checks["three_laws"].passed)
+            joined = " | ".join(report.violations)
+            self.assertIn("Three Laws", joined,
+                          f"violations should mention Three Laws: {joined!r}")
+
+    def test_banned_phrases_dock_points(self):
+        """A prompt containing 'streamlined approach' must fail the
+        no-banned-phrases check (dropping its 5 pts) AND list the phrase
+        in violations."""
+        # Otherwise-perfect prompt (100 pts) + banned phrase ⇒ 95 pts.
+        body = (
+            "## THE THREE LAWS\nLaw 1, Law 2, Law 3.\n\n"
+            "## LMC Protocol\nLead-Manager-Checker.\n\n"
+            "## Scope\nFiles owned. Responsibilities: x.\n\n"
+            "Fresh context per dispatch with self-contained brief.\n\n"
+            "Worker-mark-done.sh writes `.done.json`.\n\n"
+            "For Linear tickets, prefer a streamlined approach to save "
+            "the dispatcher some round-trips.\n"
+        )
+        with tempfile.TemporaryDirectory() as tmp:
+            path = self._write(Path(tmp), "oracle", body)
+            report = audit_agent_prompt(path)
+            self.assertFalse(
+                report.checks["no_banned"].passed,
+                "banned-phrase check should fail",
+            )
+            self.assertEqual(report.checks["no_banned"].evidence,
+                             "streamlined approach")
+            self.assertEqual(
+                report.score, 95,
+                f"every check except no_banned should pass: {report.checks}",
+            )
+            joined = " | ".join(report.violations).lower()
+            self.assertIn("banned phrase", joined)
+
+
+# ---------------------------------------------------------------------------
+# Suite audit against the real shipped templates
+# ---------------------------------------------------------------------------
+
+
+class TestAuditAisbSuiteAgainstRealRepo(unittest.TestCase):
+    """The audit must run end-to-end against the templates that ship with
+    the repo. This is the closest we can get to a post-install OMEGA_HOME
+    without actually running the installer."""
+
+    def test_audit_aisb_suite_runs_against_real_repo(self):
+        if not TEMPLATES.is_dir():
+            self.skipTest("AISB templates not present in repo")
+        with tempfile.TemporaryDirectory() as tmp:
+            home = _seed_real_aisb(Path(tmp))
+            report = audit_aisb_suite(home)
+            # The real suite ships 13 named agents + CLAUDE.md (master)
+            # + lmc-protocol.md = 15 .md files at the top level.
+            self.assertGreaterEqual(
+                len(report.per_agent), 10,
+                f"expected ≥10 agents in real suite, got {len(report.per_agent)}",
+            )
+            self.assertIsInstance(report.average_score, float)
+            self.assertIsInstance(report.orchestration_chain_intact, bool)
+            # Every report should have an agent_id and a score in range.
+            for r in report.per_agent:
+                self.assertTrue(r.agent_id, "agent_id should not be empty")
+                self.assertGreaterEqual(r.score, 0)
+                self.assertLessEqual(r.score, 100)
+
+    def test_orchestration_health_against_real_repo(self):
+        if not TEMPLATES.is_dir():
+            self.skipTest("AISB templates not present in repo")
+        with tempfile.TemporaryDirectory() as tmp:
+            home = _seed_real_aisb(Path(tmp))
+            oh = orchestration_health(home)
+            # CLAUDE.md and oracle.md are core to the suite — they MUST
+            # exist after install. If either is missing the suite is broken.
+            self.assertTrue(
+                oh["aisb_master_present"],
+                "AISB master CLAUDE.md must exist in the shipped suite",
+            )
+            self.assertTrue(
+                oh["oracle_present"],
+                "oracle.md must exist in the shipped suite",
+            )
+            # Shared `.done.json` vocabulary is a float in [0, 1].
+            overlap = oh["shared_vocab_overlap"]
+            self.assertIsInstance(overlap, float)
+            self.assertGreaterEqual(overlap, 0.0)
+            self.assertLessEqual(overlap, 1.0)
+
+
+if __name__ == "__main__":
+    unittest.main()

package/omega/Agentik_Engine/tests/test_tui_runtime.py

@@ -176,5 +176,111 @@ class TestPaperclipMenuIntegration(unittest.TestCase):
                 f"arrow menu must wire {action} (user asked for it in v0.19.37)")
 
 
+class TestChatFirstRedesign(unittest.TestCase):
+    """v0.19.39 — the TUI must open on CONVERSATIONS (live tmux sessions),
+    not on an action menu. Setup/config/infra/audits/scrape land in
+    sub-menus. These tests lock in the new layout so a careless refactor
+    doesn't bring back the v0.19.38 action-first menu."""
+
+    def test_conversations_section_appears_before_menu(self):
+        """The 'CONVERSATIONS' section header must appear in the source
+        BEFORE the 'MENU' sub-menu list — the redesign's whole point is
+        that chats are primary, settings are secondary. Match literal
+        ``_section("X")`` calls only (skip comments/docstrings)."""
+        import inspect
+        from omega_engine.tui import _arrow_menu
+        src = inspect.getsource(_arrow_menu)
+        conv_pos = src.find('_section("CONVERSATIONS")')
+        menu_pos = src.find('_section("MENU")')
+        self.assertGreater(conv_pos, 0,
+            "TUI must have a _section(\"CONVERSATIONS\") call")
+        self.assertGreater(menu_pos, 0,
+            "TUI must have a _section(\"MENU\") call for sub-menus")
+        self.assertLess(conv_pos, menu_pos,
+            "_section(\"CONVERSATIONS\") must render BEFORE _section(\"MENU\") "
+            "— the chat-first redesign requires it (v0.19.39)")
+
+    def test_dot_status_indicators_present(self):
+        """Each conversation row must show a status dot ● (alive) / ○
+        (off). Without dots the user can't tell which chats are running."""
+        import inspect
+        from omega_engine.tui import _arrow_menu
+        src = inspect.getsource(_arrow_menu)
+        for dot in ("●", "○"):
+            self.assertIn(dot, src,
+                f"menu must use {dot} status dot for live/off chats")
+        # The helper that renders dots must exist.
+        self.assertIn("_dot(", src,
+            "menu must have a _dot() helper for status indicators")
+
+    def test_submenu_dispatch_present(self):
+        """The new sub-menu pattern (`submenu:audits`, `submenu:setup`,
+        `submenu:infra`, `submenu:health`, `submenu:paperclip`) must be
+        wired AND the dispatch must handle them via _open_submenu()."""
+        import inspect
+        from omega_engine.tui import _arrow_menu
+        src = inspect.getsource(_arrow_menu)
+        for sub in ("submenu:audits", "submenu:setup", "submenu:infra",
+                    "submenu:health", "submenu:paperclip"):
+            self.assertIn(sub, src,
+                f"menu must declare {sub} as a sub-menu entry")
+        # The dispatch must indirect through _open_submenu.
+        self.assertIn("_open_submenu(", src,
+            "main loop must call _open_submenu() to render sub-menus")
+        # Sub-menu items provider exists.
+        self.assertIn("_submenu_items(", src,
+            "sub-menu rendering must use a _submenu_items() factory")
+
+    def test_attach_action_handler_present(self):
+        """The new `attach:<session>` action lets the user jump into a
+        live Oracle or Worker tmux session directly from the menu."""
+        import inspect
+        from omega_engine.tui import _arrow_menu
+        src = inspect.getsource(_arrow_menu)
+        self.assertIn('action.startswith("attach:")', src,
+            "menu must handle attach:<session> actions to let the user "
+            "jump into live Oracle/Worker sessions")
+        # Should use tmux select-window OR switch-client.
+        self.assertTrue(
+            "switch-client" in src or "select-window" in src,
+            "attach handler must use tmux select-window / switch-client")
+
+    def test_omega_window_alive_helper_used(self):
+        """The TUI status dots for AISB / Hermès rely on the
+        tmux.omega_window_alive() helper added in v0.19.39 — without it
+        we have no way to know if those windows are running."""
+        import inspect
+        from omega_engine.tui import _arrow_menu
+        src = inspect.getsource(_arrow_menu)
+        self.assertIn("omega_window_alive", src,
+            "menu must call tmux.omega_window_alive() to render the "
+            "AISB / Hermès status dots")
+
+    def test_paperclip_status_dot_inline_in_main_menu(self):
+        """The Paperclip dashboard row in QUICK ACTIONS must show a
+        live status dot — the user must see at-a-glance whether the
+        Paperclip daemon is running."""
+        import inspect
+        from omega_engine.tui import _arrow_menu
+        src = inspect.getsource(_arrow_menu)
+        self.assertIn("_paperclip_status_quick", src,
+            "menu must use the inline Paperclip probe to render its dot")
+        # Must integrate the new chantier-4 is_running() probe.
+        self.assertIn("paperclip_bridge", src)
+
+
+class TestOmegaWindowAliveHelper(unittest.TestCase):
+    """tmux.omega_window_alive() — the helper the chat-first TUI uses
+    to know whether AISB-chat / Hermès-chat are running."""
+
+    def test_returns_false_when_no_omega_session(self):
+        """When the Omega master tmux session is dead, ANY window query
+        must return False — never raise."""
+        from omega_engine.tmux import omega_window_alive
+        # Use a definitely-unique window name to avoid colliding with
+        # any real session the developer might have running.
+        self.assertIsInstance(omega_window_alive("____nonexistent_xyz"), bool)
+
+
 if __name__ == "__main__":
     unittest.main()

package/omega/Agentik_SSOT/VERSION

@@ -1 +1 @@
-0.19.38
+0.19.39

package/omega/Agentik_SSOT/docs/AUDIT-V0.19.39.md

@@ -0,0 +1,161 @@
+# OmegaOS v0.19.39 — chat-first TUI + rules folder + prompt audit + Paperclip live sync
+
+> 4 parallel chantiers landed in one ship.
+> The user's invariant: *"l'utilisateur, une fois qu'il a setup tout l'outil
+> OmegaOS, doit être 100% fonctionnel. Il n'a rien à faire à part l'utiliser."*
+
+## 1. What changed
+
+| Chantier | Owner | Files touched | Net effect |
+|---|---|---|---|
+| **#1 TUI redesign (chat-first)** | main session | `tui.py` (+200 lines), `tmux.py` (+14 lines), `tests/test_tui_runtime.py` (+87 lines) | The TUI opens on CONVERSATIONS (AISB / Hermès / live Oracles / live Workers with ●/○ status dots) instead of an action menu. Everything else collapses into **MENU** with sub-menus. |
+| **#2 Rules folder** | background agent | `omega/Agentik_SSOT/rules/{three-laws,orchestration,prompt-protocols,audit-gates,scope-safety,verified-completion}.md` (6 new files, 1250 lines), `constitution.md` (+frontmatter only) | The rule set every LLM CLI reads is now COMPLETE. 7 files, YAML-frontmatter envelope, full cross-references, ~1300 lines total. No fabrication — every protocol sourced from existing docs. |
+| **#3 Prompt audit + doctor sections** | background agent | `omega_engine/prompt_audit.py` (395 lines, new), `tests/test_prompt_audit.py` (199 lines, new), `cli.py` (+39 lines) | New `omega doctor` sections `prompts` and `orchestration`. The audit scores each agent role /100 against Three Laws + LMC + `.done.json` references. Surfaces real drift (current suite average 52/100). |
+| **#4 Paperclip live status** | background agent | `omega_engine/paperclip_bridge.py` (+`is_running()` + `PaperclipStatus`), `tests/test_paperclip_status.py` (new) | TUI can show ●/○ next to "Paperclip dashboard" with the live port. 3-tier probe (pidfile → port-scan → none), ≤0.3s worst case, never raises. |
+| **#5 Integration + ship** | main session | `package.json`, `pyproject.toml`, `__init__.py`, `VERSION`, this doc | Version bump, commit, push, npm publish. |
+| **#6 Role-prompt enrichment** | follow-up (NOT in this ship) | — | The doctor surfaces 10 weak role prompts; enriching them to ≥80/100 is intentionally deferred — the audit infrastructure is what we needed. |
+
+## 2. The new TUI (chat-first)
+
+```
+── CONVERSATIONS ──
+   ●  AISB master                  claude (Max OAuth)
+   ○  Hermès                       claude (Anthropic API)
+
+   — Active Oracles (2) —
+   ●  Causio-oracle-2              project: Causio
+   ●  DentistryGPT-oracle          project: DentistryGPT
+   — Active Workers (1) —
+   ●  DentistryGPT-worker-3-ux-fix task: ux-fix
+
+── QUICK ACTIONS ──
+   + New AISB chat                 fresh session
+   + New Hermès chat               fresh session
+   + New project                   Genesis pipeline
+   Run a mission                   verified completion
+   ○  Paperclip dashboard          not running
+
+── MENU ──
+   Quality Arsenal                 17 forensic audits
+   Setup & config                  LLM: claude_code
+   Infrastructure                  sessions, scrape
+   Health checks                   doctor, status
+   Paperclip governance            register, status
+
+── EXIT ──
+   Detach                          session keeps running
+   Quit Omega                      kills the tmux session
+```
+
+**Picking any conversation row** (Oracle / Worker / AISB / Hermès) attaches to
+that tmux session via `tmux select-window` (for Omega windows) or
+`tmux switch-client` (for foreign sessions). One click → in the conversation.
+
+**Sub-menus** open in cascaded fzf with `← back` exit rows.
+
+## 3. The rules folder — what an LLM now reads at runtime
+
+```
+omega/Agentik_SSOT/rules/
+├── constitution.md         (frontmatter: priority=1) — the Prime Principle
+├── three-laws.md           (priority=2) — operational discipline per law
+├── orchestration.md        (priority=3) — L0-L5 dispatch hierarchy
+├── prompt-protocols.md     (priority=4) — brief/done/blocked schemas + LMC
+├── audit-gates.md          (priority=5) — 17 Quality Arsenal audits as gates
+├── scope-safety.md         (priority=6) — files_owned + Sacred Scopes
+└── verified-completion.md  (priority=7) — done_clean contract + third-party rule
+```
+
+These files are mirrored into every LLM's persona dir at install time
+(via `step_personas` from v0.19.38). So whether the operator runs
+`claude`, `gemini`, `codex`, `qwen`, or `opencode` inside an AISB chat,
+they ALL see the same complete rule set — no per-LLM drift.
+
+## 4. The new `omega doctor` output (sections that didn't exist before)
+
+```
+omega doctor — OMEGA_HOME=…/Omega
+  …
+  -- personas --                          (NEW in v0.19.38)
+  [ok] canonical: Agentik_SSOT/personas/OMEGAOS-CONTEXT.md (3402B)
+  [ok] chat-contexts/aisb-master/: 8 persona files
+  [ok] chat-contexts/hermes/: 8 persona files
+  …
+  -- prompts --                           (NEW in v0.19.39)
+  [ok]   CLAUDE: 90/100
+  [warn] morpheus: 75/100 — missing: LMC protocol
+  [warn] link: 65/100 — missing: LMC protocol
+  [FAIL] oracle: 45/100 — missing: LMC protocol, `.done.json` contract
+  [warn] average suite score: 52.0/100
+  [warn] weak prompts (<60): architect, construct, keymaker, …
+
+  -- orchestration --                     (NEW in v0.19.39)
+  [ok] AISB master prompt
+  [ok] Oracle role prompt
+  [ok] Worker-class prompts
+  [ok] Checker prompts (Seraph/Smith)
+  [ok] LMC protocol document
+  [warn] shared `.done.json` vocab: 33% of agents
+```
+
+The 52/100 average is **real drift**, not a bug. Most role prompts rely
+on the engine's `load_agent_prompt()` to concatenate `lmc-protocol.md`
+at spawn time, so the on-disk role file is silent. The audit makes that
+drift VISIBLE — an operator editing `oracle.md` now has a clear signal
+that the contract is implicit. Enriching the role files to score ≥80
+is chantier #6, deferred to v0.19.40.
+
+## 5. Paperclip status integration
+
+`omega_engine.paperclip_bridge.is_running()` returns a `PaperclipStatus`
+with `running: bool, pid, port, url, detection`. Three detection paths:
+
+| # | Method | Latency | Hint emitted in TUI |
+|---|---|---|---|
+| 1 | `~/.paperclip/run/dashboard.pid` + `os.kill(pid, 0)` | ~5ms | `localhost:8080` |
+| 2 | TCP connect 127.0.0.1:8080, 0.2s timeout | ≤200ms | `localhost:8080` |
+| 3 | Neither — fall through | <1ms | `not running` |
+
+The TUI's QUICK ACTIONS row renders a ●/○ dot using this probe — the
+user sees at-a-glance whether their Paperclip governance daemon is live.
+
+## 6. Multi-agent integration — the user's question, answered with code
+
+| Question (from the user's brief) | Answer | File reference |
+|---|---|---|
+| Multi-agents bien setup? | ✅ 14 agents (Hermès + 13 AISB) — templates landed at install via `step_aisb_suite`; persona context mirrored to all 10 LLM filenames via `step_personas`. | `bootstrap/lib/steps.sh:279-293` + `omega_engine/personas.py` |
+| Tmux orchestration AISB/Oracle/Workers? | ✅ Session naming convention parsed by `tmux.categorize()`; TUI now LISTS them with status dots and one-click attach. | `omega_engine/tmux.py:47-90` + `tui.py:528-557` |
+| Rules respectés pour chaque LLM? | ✅ 7 rule files at `Agentik_SSOT/rules/` are mirrored to every LLM persona dir; doctor's `prompts` section verifies role files reference them. | `Agentik_SSOT/rules/*.md` + `omega doctor prompts` |
+| Dossier maître linké pour le LLM? | ✅ `Agentik_SSOT/personas/OMEGAOS-CONTEXT.md` is the canonical; `Agentik_SSOT/agents/aisb/CLAUDE.md` is the AISB master; both auto-mirrored to per-LLM filenames (CLAUDE.md, GEMINI.md, AGENTS.md, QWEN.md, .opencode/CONTEXT.md, …) at install time. | `step_personas` from v0.19.38 |
+| Tout setup à l'install, rien à faire post-install? | ✅ Install steps 25 (aisb-suite), 37 (hermes-brief), 38 (personas) all eager-seed. `npx -y @agentikos/omega-os@latest --full` is sufficient. | `install.sh STEPS[]` |
+| Visibilité sur ce qui se passe? | ✅ TUI chat-first view + `omega doctor` 23 sections (incl. NEW personas/prompts/orchestration). | `tui.py::_arrow_menu` + `cli.py::cmd_doctor` |
+
+## 7. Tests (regression-locked)
+
+| Chantier | New tests | Suite total |
+|---|---|---|
+| Baseline (v0.19.38) | — | 627 passed |
+| #1 TUI chat-first | +7 (TestChatFirstRedesign + TestOmegaWindowAliveHelper) | +7 |
+| #3 Prompt audit | +5 (full-score, missing-laws, banned-phrases, real-suite, real-orchestration) | +5 |
+| #4 Paperclip status | +5 (no-pidfile, stale-pidfile, live-pidfile, port-scan, url-field) | +5 |
+| **v0.19.39 total** | **+17 new** | **644 passed, 0 regressions** |
+
+Chantier #2 (rules folder) is documentation-only — no Python code, no tests
+needed; format validated by manual grep + YAML parse.
+
+## 8. Verdict
+
+✅ TUI is now **conversation-first** as the user requested ("L'objectif…
+c'est d'avoir une interface extrêmement simple… cette interface permet de
+voir la conversation avec AISB… ensuite, de voir les conversations avec
+les oracles et les conversations avec les workers").
+✅ Setup/config/audits/scrape/governance moved to sub-menus reachable via
+**MENU** (one row).
+✅ Paperclip dashboard has a live status dot and is reachable in one pick.
+✅ Rules folder is COMPLETE (7 files, 1301 lines, cross-referenced).
+✅ `omega doctor` now surfaces the orchestration health (prompts + chain).
+✅ No regression in existing 627 tests.
+
+The user's "il n'a rien à faire à part l'utiliser" invariant is preserved:
+one `npx -y @agentikos/omega-os@latest --full` and the new menu, the new
+rules, the new audit, and the live Paperclip indicator are all in place.

package/omega/Agentik_SSOT/rules/audit-gates.md

@@ -0,0 +1,189 @@
+---
+id: audit-gates
+layer: L0-governance
+applies_to: [aisb, oracle, worker]
+priority: 5
+---
+
+# Audit Gates — Quality Arsenal as System Contract
+
+> The 17 Quality Arsenal audits are **not just commands a human runs**.
+> They are *gates* that lifecycle events at L3–L5 must pass before a
+> `done.json` may state `done_clean`. This file fixes which audits gate
+> which events, how the Gestalt-Popper methodology bakes into the
+> grader, and the verified-completion thresholds the engine enforces.
+
+## The 17 audits (catalogued in `../audits/`)
+
+| Audit | Domain | Question it answers | Threshold |
+|---|---|---|---|
+| `codeaudit` | Code | Is the code SOLID? | 85/100 |
+| `flowaudit` | User flows | Does the experience WORK? | 85/100 |
+| `uiuxaudit` | UI design | Is the interface BEAUTIFUL? | 85/100 |
+| `refontaudit` | Redesign | Does the redesign hold? | 85/100 |
+| `debugaudit` | Runtime | What is BROKEN right now? | 85/100 |
+| `featureaudit` | Features | Is the product COMPLETE? | 85/100 |
+| `perfaudit` | Performance | Is it FAST enough? | 85/100 |
+| `secaudit` | Security | Is it SECURE? | 85/100 |
+| `a11yaudit` | Accessibility | Is it ACCESSIBLE? | 85/100 |
+| `seoaudit` | SEO | Is it DISCOVERABLE? | 85/100 |
+| `dataaudit` | Data | Is the data INTACT? | 85/100 |
+| `apiaudit` | API | Is the API SOLID? | 85/100 |
+| `copyaudit` | Copy | Is the copy CLEAR? | 85/100 |
+| `dxaudit` | DX | Is the DX SMOOTH? | 85/100 |
+| `motionaudit` | Motion | Is the motion PURPOSEFUL? | 85/100 |
+| `automationaudit` | Automation | Is automation RELIABLE? | 85/100 |
+| `logicaudit` | Logic | Is the logic OPTIMAL? | 85/100 |
+| `retentionaudit` | Retention | What FEATURES are missing? (READ-ONLY) | — |
+
+The full definition for each lives in `../audits/<name>.yaml`
+(domain, gather tools, phases, falsification rule, fix-loop flag).
+
+## Lifecycle gates
+
+Audits are gates on *lifecycle events*, not on *human commands*. The
+engine consults the gate registry at each event and refuses progress
+if the required audits did not pass.
+
+| Event | Gate | Audits typically required |
+|---|---|---|
+| Worker `done_clean` (per subtask) | Worker gate | The audits matching the files the Worker touched (e.g. edited `*.ts` → `codeaudit`; edited `*.css` + UI components → `uiuxaudit` + `a11yaudit`). |
+| Oracle close-coherence (per mission) | Mission gate | The union of all Worker gates plus any mission-wide audits the brief declared (`brief.audit_gates`). |
+| Pre-merge / pre-ship | Ship gate | `codeaudit`, `secaudit`, plus domain-relevant audits. Project's `ship-config.json` may add more. |
+| Genesis completion (new project) | Genesis gate | `codeaudit`, `featureaudit`, `dxaudit`, `secaudit` — a freshly built project must stand on its own. |
+| Post-mission (asynchronous) | Drift gate | `debugaudit`, `perfaudit`, periodically scheduled by Hermès or the engine cadence. |
+
+Gates compose: a Worker that triggers two audits passes only if *both*
+audits exit `verdict: satisfied` with score ≥ threshold.
+
+## The Gestalt-Popper methodology
+
+Every audit (see `../docs/quality-arsenal/QUALITY-ARSENAL-PREAMBLE.md`
+and `../docs/quality-arsenal/AUDIT-VERIFICATION-CONTRACT.md`) implements:
+
+1. **Gestalt clarity gate (Phase 0).** Before any scored phase, the
+   audit identifies the *hinge* of its domain — the single element on
+   which the domain's reliability or value pivots. The canonical hinge
+   noun per audit is fixed in
+   `AUDIT-VERIFICATION-CONTRACT.md` (e.g. `codeaudit` → HINGE POINT,
+   `flowaudit` → HINGE FLOW, `secaudit` → SECURITY HINGE POINT). The
+   hinge is given **10× scrutiny** in subsequent phases.
+2. **Popper falsification.** For each scored item, the auditor states
+   *what would prove this claim wrong*. A PASS is only valid if the
+   falsifier was sought and not found. Bias toward FAIL — a 100 is
+   earned, never assumed.
+3. **Hippocratic pre/post.** Before any fix, capture baseline
+   (Phase N-1). After each fix, re-run the baseline check (Phase N+1).
+   A fix that broke a previously-working check reverts and is marked
+   `NEEDS_REVIEW`.
+4. **Before-after matrix (Phase N+4).** Every audit produces
+   `.<audit>/before-after.md` proving zero regressions. No matrix → no
+   100/100 verdict.
+5. **Fix → re-audit loop.** Bounded (typically 5 iterations). The loop
+   exits on `verdict: satisfied` *or* on iteration cap.
+
+## Mandatory minimums (per audit)
+
+These structural invariants are enforced by `metaudit` (the audit of
+audits). A skill that violates any of them fails meta and is removed
+from the gate registry until repaired.
+
+| # | Invariant | Why |
+|---|---|---|
+| 1 | At least 16 scored phases | Forensic depth — fewer phases = shallow audit. |
+| 2 | Phase N-1 (PRE-FIX BASELINE) implemented before the first fix | Hippocratic rule — can't claim "no regression" without a baseline. |
+| 3 | Phase N+4 (before-after matrix) written to `.<audit>/before-after.md` | Proof-of-work artefact required for the 100/100 verdict. |
+| 4 | Score normalised to /100 (raw may be /280, /320, /360, /400, /420 — must publish the formula) | Cross-audit comparison. |
+| 5 | HINGE identification at Phase 0 | Gestalt clarity gate. |
+| 6 | Popper falsification per scored item | Epistemic rigor. |
+| 7 | Fix → re-audit loop with explicit max iterations | Bounded recovery. |
+| 8 | Final verdict gate refuses 100/100 unless `before-after.md` shows zero regressions | Contract enforcement. |
+
+## The verified-completion contract
+
+A `done.json` may state `status: done_clean` only when **all** of:
+
+| Condition | Source |
+|---|---|
+| `audit.verdict == "satisfied"` | The grader (LMC or direct) for every required gate. |
+| `audit.scores[gate] >= threshold` (default 85/100) for each gate | `../audits/<gate>.yaml#threshold`. |
+| `regressions.length == 0` | Phase N+4 before-after matrix. |
+| `evidence.verify_exit_code == 0` | The brief's `verify_command`. |
+| `ship.result in ["ok", "skipped"]` when `ship.requested == true` | The ship pipeline (see `verified-completion.md`). |
+| Independent third party ran the *real* flow | The grader is a different agent from the executor; the verify is the real system, not a mock. |
+
+Fail any condition → `status: pending` (with `pending_actions[]` listing
+the failed conditions) or `status: failed` (when the verify itself
+errored). The engine refuses to mark a session done on the receiver's
+word alone — see `verified-completion.md`.
+
+## Routing — which audits apply
+
+Each `<audit>.yaml` declares `applies_to.changed` — the glob set that
+*triggers* the audit when a Worker's `files_owned` intersects it.
+Sample mappings:
+
+| Glob change | Audits auto-required |
+|---|---|
+| `*.py`, `*.ts`, `*.tsx`, `*.js`, `*.go`, `*.rs` | `codeaudit` |
+| `*.tsx`, `*.jsx`, `*.css`, design tokens | `uiuxaudit`, `a11yaudit`, `motionaudit` (if motion files touched) |
+| `*.env*`, `Dockerfile`, `package.json`, auth modules | `secaudit` |
+| API route handlers, OpenAPI / GraphQL schemas | `apiaudit` |
+| Database migrations, schema files | `dataaudit` |
+| Onboarding, signup, payment flows | `flowaudit` |
+| Cron specs, daemon scripts, scheduled tasks | `automationaudit` |
+| Marketing pages, SEO meta, sitemap | `seoaudit`, `copyaudit` |
+
+The Oracle expands `brief.audit_gates` from this routing table at
+dispatch time. A Worker may not narrow the gate set; it may *only*
+widen it (e.g. discovers a security implication mid-task).
+
+## Ship gate (pre-prod)
+
+When `brief.ship == true`, the ship pipeline runs before final
+`done.json`. Each step gates the next:
+
+1. `npm run build` (or equivalent) — exit 0.
+2. Whitelisted staging — only `files_owned`. Any extra file aborts.
+3. Secret scan (e.g. `gitleaks --staged`) — zero matches.
+4. Whitespace sanity (`git diff --check`) — clean.
+5. Conventional-commit message from `brief.commit_message`.
+6. Per-project ship lock (`flock`) — serialise across Oracles.
+7. Freeze flag check — if `Agentik_Runtime/locks/ship-<project>.frozen`
+   exists, abort and alert.
+8. `git pull --rebase` — clean.
+9. `git push` — clean.
+10. Deploy (project-defined command) — typically `vercel --prod` or
+    equivalent.
+11. Poll deploy status until READY/ERROR/TIMEOUT (default 10 min).
+12. Write `done.json#ship` with commit, URL, status, duration.
+
+Default deploy-failure policy is **freeze, don't rollback** — the
+freeze flag blocks further pushes on the project until the human lifts
+it. Auto-rollback is opt-in per project via `ship-config.json`.
+
+## Drift gate (continuous)
+
+`debugaudit` and `perfaudit` are scheduled to run periodically against
+the live deployed URL (typically by Hermès cadence or the engine's
+cron). A drift detection writes a `done.json` with
+`status: failed` against a synthetic "drift" mission, which AISB
+surfaces to the human and (if the project opts in) auto-dispatches a
+repair mission.
+
+## Cross-references
+
+- `constitution.md` — Verification Rule.
+- `three-laws.md` — First Law (runtime over code) is the audit
+  methodology's epistemology.
+- `prompt-protocols.md` — `brief.audit_gates`, `done.audit` schema.
+- `verified-completion.md` — the terminal contract these gates serve.
+- `scope-safety.md` — Worker gates intersect with `files_owned`.
+- `orchestration.md` — Oracle close-coherence runs the mission gate.
+- `../audits/*.yaml` — per-audit catalogue (domain, gather, phases).
+- `../docs/quality-arsenal/AUDIT-VERIFICATION-CONTRACT.md` — Hippocratic
+  pre/post protocol.
+- `../docs/quality-arsenal/QUALITY-ARSENAL-PREAMBLE.md` — Gestalt-Popper
+  methodology.
+- `../docs/LAYERS.md` — which layer runs which gate.
+- `../personas/OMEGAOS-CONTEXT.md` — provider-neutral working context.