@agentikos/omega-os 0.19.37 → 0.19.39

package/omega/Agentik_SSOT/rules/verified-completion.md

@@ -0,0 +1,216 @@
+---
+id: verified-completion
+layer: L0-governance
+applies_to: [aisb, oracle, worker, hermes]
+priority: 7
+---
+
+# Verified Completion — The Prime Principle
+
+> **Completion is derived, never declared.** No agent may assert that
+> its own work is finished. A task is finished only when the engine
+> computes it — from observable, immutable events, verified by an
+> independent third party that ran the real flow.
+>
+> This file makes the Prime Principle from `constitution.md`
+> operational: the `done.json` contract, the independent-third-party
+> requirement, the score threshold, and the reason 92% is treated as
+> 0% in this system.
+
+## Why "derived, never declared"
+
+An agent that grades its own homework converges to *"I think this is
+fine"*. That is the failure mode the Prime Principle exists to
+eliminate. Verified completion separates three roles:
+
+| Role | Permitted to say |
+|---|---|
+| Executor (Worker) | *"I ran the verify command, here's the captured exit code, stdout, stderr, and artefacts."* |
+| Grader (Oracle's close-coherence, audit graders) | *"The executor's evidence is consistent with the brief's done criteria, and the audit gates passed."* |
+| Engine | *"The mission's `done.json` is now `status: done_clean`."* |
+
+No single agent collapses these three roles. The grader is a different
+agent (or LMC Checker) from the executor. The engine writes the final
+status; the executor only produces evidence the engine consumes.
+
+## The `done.json` contract (terminal)
+
+A `done.json` is the *only* artefact the engine treats as a terminal
+state for a session. Its schema is fixed in `prompt-protocols.md`;
+this file fixes the *semantics* of each `status` value.
+
+### `status: done_clean`
+
+The engine writes this only when **all** of:
+
+1. The brief's `verify_command` exited 0, with captured stdout/stderr
+   preserved in `evidence`.
+2. Every audit in `audit.gates_required` ran to completion *and*
+   produced a verdict of `satisfied` with score ≥ threshold (default
+   85/100, per `../audits/<gate>.yaml#threshold`).
+3. `regressions: []` — Phase N+4 before-after matrix is empty in the
+   *regressions* column.
+4. The file-ownership audit (see `scope-safety.md`) found zero
+   out-of-scope edits.
+5. If `brief.ship == true`: `ship.result in ["ok", "skipped"]` and
+   the deploy poll returned `READY`.
+6. The grader is a different agent from the executor. (Self-grading
+   collapses the contract; the engine rejects it.)
+7. The grader ran the *real* flow against the *real* system — not a
+   mock, not a stub, not a description of what would happen.
+
+Any condition unmet → `status: pending` or `status: failed`.
+
+### `status: pending`
+
+The verify exited 0 *for this slice* but more work is needed to satisfy
+the user's intent. The receiver populates `pending_actions[]` with
+specific, actionable next slices. The dispatcher reads them and
+decides:
+
+- Continue this session with the next slice → re-dispatch.
+- Hand off to another agent → fresh brief.
+- Surface to the human → done at this level, but mission stays open.
+
+`pending` is **not** failure. It is honest mid-stream reporting.
+
+### `status: failed`
+
+The verify exited non-zero, an audit gate refused, a regression was
+detected, or a scope/secret violation triggered the safety mesh.
+`evidence` contains the failure trace; the receiver does not retry —
+that's the dispatcher's call after diagnosis.
+
+## The independent third party
+
+The verifier is not the executor. This is non-negotiable.
+
+| Layer | Executor | Independent verifier |
+|---|---|---|
+| L5 Worker (per subtask) | The Worker itself | The Worker's `verify_command` (script that exits 0/non-0) plus the audit graders configured in `brief.audit_gates`. |
+| L4 Oracle (close-coherence) | The Workers it spawned | A fresh audit pass — typically `seraph` in full-LMC mode (Lead-Manager-Checker) — over the union of Worker artefacts. |
+| L3 AISB (mission close) | The Oracle | A drift gate (`debugaudit` / `perfaudit` against the deployed system) plus the `done.json` reconciliation. |
+| L2 Hermès (autonomous loop) | AISB | An observation poll (was the user-visible outcome achieved?) before scheduling the next iteration. |
+
+**Same agent grading its own work = not verified.** A Worker that
+writes its `done.json` *and* its `audit.scores` *and* its `verdict` is
+not done — the engine refuses the claim and re-opens.
+
+## The "ran the real flow" rule
+
+A verifier that read the code, reasoned about it, and declared it
+correct has *not* verified. Verification means *the real system was
+exercised by the real flow*.
+
+| Acceptable verification | Unacceptable verification |
+|---|---|
+| `curl https://deployed-url/api/foo` → 200 OK | "The handler returns 200 for valid input" (read from source) |
+| Playwright run against the deployed URL, captured screenshot | "The component renders correctly" (read from JSX) |
+| Test suite run, exit 0, captured output | "All tests would pass" (read from test names) |
+| Connect to staging DB, run query, capture rows | "The migration creates the table" (read from SQL) |
+| Send the real (sandboxed) webhook, observe handler logs | "The handler would process this payload" (read from handler code) |
+
+The First Law (`three-laws.md`) is the epistemology that underwrites
+this rule. Reading is never verifying.
+
+## Why 92% ≠ done
+
+A mission whose verify command passes but whose audit gates returned
+84/100 is **not 92% done**. It is **0% done from the engine's
+perspective**. The engine writes `status: pending`, the mission stays
+open, the receiver re-dispatches.
+
+This is intentional. A system that converts *"close to passing"* into
+*"shipped"* drifts toward shipping broken software, because the gap
+between 84 and 100 is exactly the gap where defects live undetected.
+
+Concretely:
+
+- The gate threshold is a *floor*, not an *aspiration*. A 84 means
+  the audit found enough evidence of trouble to refuse.
+- Re-opening a mission to add the missing 16 points is cheap (the
+  audit already named what to fix).
+- Shipping a 84 and patching forward is expensive (rollback,
+  hotfix, customer-visible regression, trust loss).
+
+The cost asymmetry justifies the rule. The Karpathy principle of
+*goal-driven execution* says the goal here is `verdict: satisfied`,
+not `verdict: close-enough`.
+
+## The patrol — engine, not agent
+
+The engine runs a **patrol** that:
+
+1. Scans `Agentik_Runtime/state/*.done.json` every cycle.
+2. For each new file, validates it against the schema in
+   `prompt-protocols.md`.
+3. Reconciles `gates_passed` against `gates_required`.
+4. If all gates pass + zero regressions + verify exit 0 → engine writes
+   the *final* status (the receiver's `status` field is treated as a
+   *claim*; the engine confirms or downgrades).
+5. Surfaces final status to the dispatcher (Telegram, CLI, UI).
+6. Schedules close-out actions (session teardown, log archival,
+   memory consolidation).
+
+The patrol is the only writer to the mission's *engine-truth* status.
+Agents never write this directly.
+
+## Anti-patterns the patrol rejects
+
+| Anti-pattern | Rejected because |
+|---|---|
+| `done.json` with `status: done_clean` but `audit.scores` missing | Schema violation. |
+| `done.json` with `status: done_clean` written by the same agent name listed in `evidence.executor` and `audit.grader` | Self-grading. |
+| `done.json` claiming `audit.verdict: satisfied` while `audit.scores[gate] < threshold` | Verdict contradicts score. |
+| `done.json` written within 5 seconds of brief receipt | Too fast to have run the verify; flagged for inspection. |
+| `done.json` with `evidence.verify_exit_code == 0` but no `verify_stdout` capture | Evidence missing. |
+| `done.json` claiming `ship.result == ok` but the deploy poll never reached `READY` | Ship status mismatch. |
+
+Each rejection is logged to `decisions.md` with the violation reason,
+and the mission is re-opened.
+
+## The completion ladder
+
+For a multi-Worker mission, the ladder of verifications looks like:
+
+```
+Worker A    → done.json (status=done_clean, scores satisfied)  ─┐
+Worker B    → done.json (status=done_clean, scores satisfied)  ─┤
+Worker C    → done.json (status=done_clean, scores satisfied)  ─┤
+                                                                ▼
+Oracle close-coherence  → fresh audit over union of A+B+C
+                          done.json (status=done_clean)         ─┐
+                                                                 ▼
+AISB drift gate         → debugaudit/perfaudit on deployed URL
+                          done.json (status=done_clean)         ─┐
+                                                                 ▼
+Engine patrol           → reconciles, writes engine-truth status
+                                                                 ▼
+                          Telegram / CLI / UI report to L1
+```
+
+A break anywhere in the ladder collapses the mission to `pending` or
+`failed` at that level. The level above receives the truthful signal
+and decides next steps — it does not paper over a lower failure with
+its own success claim.
+
+## The bottom line
+
+Completion is what the engine writes. Everything an agent says about
+its own completion is *a claim*, subject to grader review and engine
+reconciliation. The Prime Principle is not a slogan — it is the
+algorithm by which `done_clean` reaches the human.
+
+## Cross-references
+
+- `constitution.md` — Prime Principle, Verification Rule.
+- `three-laws.md` — First Law (runtime over code) is the
+  epistemology of "ran the real flow".
+- `orchestration.md` — Oracle close-coherence pass; AISB drift gate.
+- `prompt-protocols.md` — `done.json` / `blocked.json` schemas; LMC.
+- `audit-gates.md` — which audits gate `done_clean`; thresholds.
+- `scope-safety.md` — file-ownership audit gates `done_clean`.
+- `../docs/quality-arsenal/AUDIT-VERIFICATION-CONTRACT.md` —
+  Hippocratic pre/post + before-after matrix.
+- `../docs/LAYERS.md` — which layer owns which step of the ladder.
+- `../personas/OMEGAOS-CONTEXT.md` — provider-neutral working context.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentikos/omega-os",
-  "version": "0.19.37",
+  "version": "0.19.39",
   "description": "Omega OS — installable agentic operating system with verified-completion orchestration. Event-sourced engine, 8-block rack, autonomous agents, MCP.",
   "bin": {
     "omega-os": "bin/omega-os.js"