@agentikos/omega-os 0.19.38 → 0.19.40

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.

package/omega/Agentik_SSOT/rules/constitution.md

@@ -1,3 +1,10 @@
+---
+id: constitution
+layer: L0-governance
+applies_to: [aisb, oracle, worker, hermes]
+priority: 1
+---
+
 # The Omega OS Constitution
 
 > The rules every agent at every level inherits. Provider-neutral. Compiled into

package/omega/Agentik_SSOT/rules/orchestration.md

@@ -0,0 +1,215 @@
+---
+id: orchestration
+layer: L0-governance
+applies_to: [aisb, oracle, worker, hermes]
+priority: 3
+---
+
+# Orchestration — Who Dispatches What
+
+> OmegaOS is a five-layer agentic OS with one optional governance roof
+> (L0/Paperclip). This file fixes the dispatch hierarchy, the decisions
+> log discipline, and the fresh-context template every layer uses when
+> handing work down. The architecture itself is defined in
+> `../docs/LAYERS.md`; this file makes it *operational*.
+
+## The hierarchy
+
+```
+L0  Paperclip            (optional governance roof — budget, org chart, approvals)
+L1  Human                (Telegram, CLI, web — three doors into the system)
+L2  Hermès               (meta-companion — Anthropic API, separate budget)
+L3  AISB                 (intake / orchestrator — Claude Max OAuth)
+L4  Oracle               (per-project planner — persistent tmux session)
+L5  Workers              (executors — one per subtask, .done.json verified)
+```
+
+Each layer is *independently usable*. Skip L0 and L2 and OmegaOS is
+still a complete agentic OS: a human writes intent, AISB classifies,
+Oracle plans, Workers execute, the engine verifies.
+
+## Dispatch rules
+
+The arrows below define *who is permitted to dispatch to whom*. Any
+other dispatch is a violation and the receiving layer must refuse.
+
+| From | May dispatch to | Notes |
+|---|---|---|
+| L1 Human | L2 Hermès, L3 AISB | Three doors: Telegram-to-Hermès, Telegram-to-AISB, CLI/tmux. |
+| L0 Paperclip | L2 Hermès, L3 AISB | Approval gates; never bypasses the lower layers. |
+| L2 Hermès | L3 AISB | Hermès cannot reach Oracle or Worker directly. Missions go through AISB. |
+| L3 AISB | L4 Oracle | One Oracle per project. AISB never spawns a Worker directly. |
+| L4 Oracle | L5 Workers | One Worker per subtask, with a verify command. |
+| L5 Worker | — | A Worker never dispatches. If more work is needed, it returns `status: pending` and lets Oracle decide. |
+
+**Why no skipping.** Each step adds a layer of intent translation. AISB
+turns a freeform human prompt into a typed mission. Oracle turns a
+mission into a DAG of subtasks with verify commands. A Worker that
+receives a freeform human prompt has no scope, no verify command, and
+no way to call itself done — the verified-completion contract breaks.
+
+## Roles in one line
+
+- **L0 Paperclip.** Approvals + budget + org chart. Read-only over L1–L5
+  unless a budget guard fires.
+- **L1 Human.** Author of intent. Reads final reports. Approves
+  destructive ops.
+- **L2 Hermès.** Meta-reasoning, scheduling, learning. Watches
+  observations, proposes missions, dispatches them down to L3.
+- **L3 AISB.** Intake. Classifies a mission (simple / medium / complex /
+  epic), picks a topology, hands to L4.
+- **L4 Oracle.** Per-project planner. Reads the mission, builds the
+  outcome rubric (see `audit-gates.md`), dispatches Workers, polices
+  their `done.json`, runs the close-coherence audit.
+- **L5 Worker.** Executor. Owns a strict file scope
+  (`spec.scope.files_owned`), writes `done.json` when the verify
+  command passes.
+
+## The decisions log
+
+Every layer that makes a non-trivial routing or design choice **MUST**
+append to `.orchestrator/decisions.md` in the project root:
+
+```markdown
+### [ISO-8601 timestamp] Decision title
+- **Task:** what was asked
+- **Classification:** SIMPLE / MEDIUM / COMPLEX / EPIC
+- **Decision:** what was chosen (agent, topology, audit set, scope)
+- **Rationale:** why (one line)
+- **Falsifier:** the runtime check that would prove this wrong
+```
+
+The log is append-only. Past entries are never edited — only superseded
+by a new entry that cites the old one. AISB and Oracle both write to
+the same file; Workers write only if they exercise the Third Law and
+correct a premise inside a dispatched session.
+
+Reason: when a mission is re-opened a week later, the *why* is in the
+log. Without it the next agent has to reverse-engineer past intent from
+diffs.
+
+## The fresh-context template (mandatory at every dispatch)
+
+When *any* layer dispatches to the one below it, the brief MUST contain
+the following sections. Empty sections are allowed; missing sections
+are a contract violation.
+
+```
+## Mission
+<1-2 line summary of the goal>
+
+## Purpose
+<why this matters — links the work to the human intent at L1>
+
+## Context
+<project root, deployed URL, stack, relevant prior runs>
+
+## What's Done
+<bullet list of completed work in this mission so far>
+
+## Current Task
+<specific files, line numbers, exact changes — surgical scope>
+
+## Done Criteria
+<measurable condition: a shell-checkable predicate, an audit verdict,
+ a screenshot diff, a passing test>
+
+## Verify Command
+<exact command the receiver runs to prove it satisfied Done Criteria>
+
+## Key Decisions
+<excerpts from .orchestrator/decisions.md relevant to this task>
+
+## Files in Scope
+<the receiver's spec.scope.files_owned — files it may edit>
+
+## Relevant Memories
+<pre-selected lessons-learned entries — NOT a full dump>
+```
+
+**Why both Done Criteria and Verify Command.** Without `Done Criteria`
+the receiver redefines "done" mid-stream. Without `Verify Command` the
+dispatcher cannot independently confirm — and the verified-completion
+contract demands an independent third party (see
+`verified-completion.md`).
+
+## Fresh context vs context overlap
+
+When a layer hands a sub-mission to a fresh agent, the dispatcher
+decides between two patterns:
+
+| Pattern | When | Cost |
+|---|---|---|
+| **Continue agent** | High overlap with prior subtask; the prior agent already holds the relevant files and state in working memory. | Cheap but risks context bloat past compaction thresholds. |
+| **Spawn fresh** | New domain, new files, new specialist. The dispatcher pre-inlines a summary of prior results into the fresh brief. | Slightly more expensive, guarantees a clean slate. |
+
+Default is *spawn fresh* for any subtask that crosses a layer or a
+domain boundary. Continue only inside a single layer's working session.
+
+## Multi-Oracle on the same project
+
+Multiple Oracles can run in parallel on the same project. The engine
+serialises *file ownership*, not Oracle count.
+
+- AISB checks the per-project Oracle registry before dispatching. If
+  an Oracle is *idle* (no Workers, at prompt, >5 min), AISB reuses
+  it. Otherwise AISB spawns Oracle #2 (`oracle-<Project>-2`).
+- Each Oracle declares `files_owned` for its mission. Two Oracles
+  cannot claim overlapping files.
+- The patrol auto-cleans dead Oracles every 5 minutes.
+- A registry file at `Agentik_Runtime/oracles/<Project>-<id>.json`
+  records the Oracle's mission, scope, and heartbeat.
+
+## Worker batching (parallel-safe)
+
+Inside a single Oracle, Workers may run *in parallel* if and only if
+their file footprints are disjoint. The Oracle's plan groups subtasks
+into batches:
+
+- **Narrow** subtasks: identifiable file set, no overlap with other
+  narrow tasks → packable into a batch of up to N (typical N = 3 or 4).
+- **Broad** subtasks: vague scope, no identifiable file footprint →
+  run alone, serially.
+- **Terminal** subtasks: touch infrastructure (env files, package
+  manifests, migrations) → always run alone, after all batches.
+
+Two Workers on the same file at the same time is a contract violation
+even if their edits "wouldn't conflict" — the assertion of disjointness
+itself is the contract.
+
+## Close-coherence (Oracle's final check)
+
+When all Workers report `done_clean`, the Oracle runs a *close-
+coherence* pass before reporting up to AISB:
+
+1. Re-read the mission brief.
+2. For each Worker, confirm its `done.json` matches the brief's slice.
+3. Run the audit set the brief requires (see `audit-gates.md`).
+4. Write the Oracle's own `done.json` with `consensus_score`,
+   `regressions`, and the final verdict.
+
+An Oracle that skips close-coherence has not finished its job, even if
+every Worker did.
+
+## The "no idle wait" invariant
+
+The Third Law applies to *every* dispatched session in this hierarchy
+(L2 ↔ L3 ↔ L4 ↔ L5). The only sessions where a question may be asked
+of a human are sessions L1 owns directly — typically an interactive
+shell or a Telegram DM the human is actively reading.
+
+Practical detection rule for an agent: *"Am I attached to a tmux
+session whose name starts with `oracle-`, `aisb-`, or contains
+`-worker-`?"* If yes, no questions; decide and proceed
+(`prompt-protocols.md` for the exact `blocked.json` fallback).
+
+## Cross-references
+
+- `constitution.md` — Prime Principle, Three Laws.
+- `three-laws.md` — expanded Third Law (no idle wait).
+- `prompt-protocols.md` — brief / done.json / blocked.json schemas.
+- `audit-gates.md` — which audits gate which dispatch transitions.
+- `scope-safety.md` — `spec.scope.files_owned` discipline.
+- `verified-completion.md` — terminal states an Oracle/Worker may report.
+- `../docs/LAYERS.md` — formal L1–L5 architecture and credential model.
+- `../personas/OMEGAOS-CONTEXT.md` — provider-neutral working context.

package/omega/Agentik_SSOT/rules/prompt-protocols.md

@@ -0,0 +1,219 @@
+---
+id: prompt-protocols
+layer: L0-governance
+applies_to: [aisb, oracle, worker, hermes]
+priority: 4
+---
+
+# Prompt Protocols — Brief, Done, Blocked
+
+> Every dispatch in OmegaOS is a contract: a brief in, a `done.json`
+> out, with `blocked.json` as the escape valve. This file fixes the
+> three schemas, the LMC (Lead-Manager-Checker) variant for grader
+> agents, and the "no idle wait" rule that turns the Third Law into
+> a protocol guarantee.
+>
+> See `../agents/aisb/lmc-protocol.md` for the in-agent LMC reference
+> (when full LMC is used vs lite vs direct).
+
+## The three artefacts
+
+| Artefact | Direction | Required keys | Lifecycle |
+|---|---|---|---|
+| `brief.json` (or inline prompt) | Down (dispatcher → receiver) | mission, purpose, files_owned, done_criteria, verify_command, ship | Created per dispatch, immutable. |
+| `done.json` | Up (receiver → dispatcher) | status, started_at, finished_at, evidence, score (when audited), ship (when applicable) | Created exactly once per receiver, terminal. |
+| `blocked.json` | Sideways (receiver → orchestrator state) | session, blocked_at, question, best_guess, fallback_action, can_resume_without_answer | May exist *in parallel* with `done.json` — surfaces the question to the human asynchronously. |
+
+The schemas below are the contract. Engine and Telegram bridge both
+parse them; deviations break notifications and audit replay.
+
+## brief.json schema
+
+```json
+{
+  "id":              "<uuid-v4>",
+  "mission":         "<1-2 line goal>",
+  "purpose":         "<why this matters at L1>",
+  "context": {
+    "project_root":  "/absolute/path",
+    "deployed_url":  "https://...",
+    "stack":         "next.js | python | go | …",
+    "prior_runs":    ["<done.json paths>"]
+  },
+  "whats_done":      ["<bullet>", "<bullet>"],
+  "current_task":    "<files, line numbers, exact changes>",
+  "done_criteria":   "<measurable predicate>",
+  "verify_command":  "<exact shell command>",
+  "key_decisions":   ["<excerpt from decisions.md>"],
+  "spec": {
+    "scope": {
+      "files_owned": ["src/foo.ts", "tests/foo.test.ts"]
+    }
+  },
+  "relevant_memories": ["<lesson-id>"],
+  "ship":              false,
+  "audit_gates":       ["codeaudit"],
+  "lifecycle":         "ephemeral | persistent"
+}
+```
+
+- `mission` ≤ 200 chars (longer = dispatcher failed to decompose).
+- `files_owned` is a hard boundary; see `scope-safety.md`.
+- `verify_command` MUST be a shell command, not prose; wrap sequences
+  in a script that exits 0 on success.
+- `ship` defaults to `false`; set true only when the prompt contains a
+  ship/deploy/push directive or `ship-config.json` opts in.
+- `audit_gates` lists Quality Arsenal audits that must pass before
+  `status: done_clean` (see `audit-gates.md`).
+- `lifecycle: ephemeral` lets the dispatcher close the receiver on
+  `done_clean`; `persistent` keeps it alive for follow-up.
+
+## done.json schema
+
+```json
+{
+  "agent":             "<oracle-name | worker-name>",
+  "project":           "<slug>",
+  "status":            "done_clean | pending | failed",
+  "started_at":        "<ISO-8601>",
+  "finished_at":       "<ISO-8601>",
+  "duration_sec":      0,
+  "mission":           "<copy of brief.mission>",
+  "evidence": {
+    "verify_command":   "<command run>",
+    "verify_exit_code": 0,
+    "verify_stdout":    "<captured>",
+    "verify_stderr":    "<captured>",
+    "artefacts":        ["path/to/screenshot.png", "path/to/log"]
+  },
+  "audit": {
+    "gates_required":  ["codeaudit", "secaudit"],
+    "gates_passed":    ["codeaudit", "secaudit"],
+    "scores":          {"codeaudit": 92, "secaudit": 88},
+    "verdict":         "satisfied | partial | unsatisfied"
+  },
+  "regressions":       [],
+  "pending_actions":   [],
+  "ship": {
+    "requested":       false,
+    "result":          "ok | failed | skipped | frozen",
+    "commit":          "<sha or null>",
+    "deploy_url":      "<url or null>",
+    "deploy_status":   "READY | ERROR | TIMEOUT | null"
+  },
+  "report_path":       "<path/to/report.md>"
+}
+```
+
+### Status values + forbidden patterns
+
+| Status | Meaning | Dispatcher action |
+|---|---|---|
+| `done_clean` | Verify passed, all audit gates passed, zero regressions. | Closes session (if ephemeral), forwards report up. |
+| `pending` | Verify passed *for this slice*; `pending_actions[]` lists next slices. | Keeps session alive, decides continue vs hand off. |
+| `failed` | Verify failed, audit gate refused, or regression detected. | Keeps session alive, reads evidence, re-dispatches. |
+
+Forbidden: `done_clean` without `verify_exit_code == 0`; with
+`regressions[]` non-empty; with any required gate missing from
+`gates_passed`; after a ship that returned `failed` or `frozen`. Any
+violation → dispatcher rejects the claim, re-opens the mission, logs
+to `.orchestrator/decisions.md`. Absence of `done.json` is **not**
+success — patrol waits.
+
+## blocked.json schema
+
+```json
+{
+  "session":                   "<tmux session name>",
+  "blocked_at":                "<ISO-8601>",
+  "question":                  "<what is ambiguous>",
+  "best_guess":                "<the receiver's recommendation>",
+  "fallback_action":           "<what the receiver is doing meanwhile>",
+  "can_resume_without_answer": true,
+  "human_required_for":        "<credential | destructive op | scope expansion | null>"
+}
+```
+
+Lives at `Agentik_Runtime/state/blocked-<session>.json`. The patrol
+polls this directory; when a file appears, the human is notified via
+Telegram (Hermès or AISB, depending on routing).
+
+### Legal vs illegal blocks
+
+A `blocked.json` is legal only when (a) the block is genuine
+(credential missing, destructive op outside scope, true semantic
+ambiguity with no safe default), (b) `fallback_action` is *executing
+right now*, and (c) `can_resume_without_answer: true`.
+
+Illegal blocks (these are *preferences*, not blocks — decide and
+proceed per the Third Law):
+
+- "I'd like to confirm before proceeding."
+- "Three options exist, which would you prefer?"
+- "I want the user to validate the approach before I code."
+
+## The LMC variant (Lead-Manager-Checker)
+
+LMC is the *optional* grader topology used by audit-grade agents
+(e.g. `seraph`). Most agents work direct — Lead alone — because
+Manager/Checker overhead is wasted on routing or simple execution.
+See `../agents/aisb/lmc-protocol.md` for the canonical table.
+
+| Agent role | LMC mode | Why |
+|---|---|---|
+| Audit grader (seraph) | **Full LMC** (Lead + Manager + Checker) | Independent validation is the whole point of audit. |
+| Planner (keymaker) | **Lite LMC** (Lead + Manager; Lead validates) | Plans benefit from structured generation. |
+| Everyone else | **Direct** | Speed > ceremony for execution, research, routing. |
+
+Manager output:
+
+```
+BRIEF: <1-line>   STATUS: DONE | PARTIAL | BLOCKED
+CONFIDENCE: <0.0-1.0>   ARTIFACTS: <files>
+```
+
+Checker verdict (full LMC only):
+
+```
+DECISION: PASS | FAIL   CONFIDENCE: <0.0-1.0>
+ISSUES: <list>   FEEDBACK: <next-attempt guidance>
+```
+
+Three FAIL verdicts in a row → escalate to dispatcher (do not loop).
+
+## The "no idle wait" rule
+
+Sessions identified as *dispatched* (per `orchestration.md`) **MUST
+NEVER** stop with an idle prompt. The only legal terminal states are:
+
+1. `done.json` with `status: done_clean`.
+2. `done.json` with `status: pending` and non-empty `pending_actions[]`.
+3. `done.json` with `status: failed` and non-empty
+   `evidence.verify_stderr`.
+4. `done.json` plus a `blocked.json` whose `fallback_action` is
+   currently executing.
+
+Violation phrases a transcript audit will flag: *"Which path should I
+take?"*, *"Should I proceed?"*, *"Awaiting confirmation"*, *"Confirm
+before I continue"*. Replace any of them with a decision written to
+`decisions.md` and immediate execution of the best path.
+
+## Idempotency
+
+`done.json` is written exactly once per session; duplicate writes are
+rejected by mtime. To *correct* a prior `done.json` (e.g. a regression
+discovered after `done_clean`), write a new
+`done-correction-<timestamp>.json` referencing the original and let
+the dispatcher reconcile.
+
+## Cross-references
+
+- `constitution.md` — Prime Principle, Three Laws.
+- `three-laws.md` — Third Law (no idle wait) in detail.
+- `orchestration.md` — dispatch hierarchy + decisions log.
+- `audit-gates.md` — `audit_gates[]` semantics in brief / done.
+- `scope-safety.md` — `files_owned` enforcement.
+- `verified-completion.md` — the terminal contract done.json fulfils.
+- `../agents/aisb/lmc-protocol.md` — LMC mode reference.
+- `../docs/LAYERS.md` — which sessions are "dispatched".
+- `../personas/OMEGAOS-CONTEXT.md` — provider-neutral working context.